NRFrame.GetTrackables を読み解いてみる

概要

ImageTracking の仕組みを理解するために NRFrame.GetTrackables を読み解いてみます。 個人的な読解結果であるため誤りが含まれている可能性があることをご了承ください。

目次

確認環境

• NRSDK 1.2.1

解説

拾い読み

NRFrame.GetTrackables から続く処理を拾い読みしました。以下が要点かと思います。

• NRFrame.GetTrackables
  • NRTrackableManager.GetTrackables
    • UpdateTrackables を呼び出す
    • m_AllTrackables を m_NewTrackables と m_OldTrackables に振り分ける
  • NRTrackableManager.UpdateTrackables
    • trackablelist_handle = NativeTrackable.CreateTrackableList()
    • NativeTracking.UpdateTrackables(trackablelist_handle, trackable_type)
      • trackable_type : TrackableType (BASE/PLANE/IMAGE)
    • count = NativeTrackable.GetSize(trackablelist_handle)
    • count 回繰り返す
      • trackable_handle = NativeTrackable.AcquireItem(trackablelist_handle, index)
      • Create(trackable_handle, m_NativeInterface) を呼び出す
    • NativeTrackable.DestroyTrackableList
  • NRTrackableManager.Create
    • trackableType = NativeTrackable.GetTrackableType(trackable_handle)
    • trackableType が TRACKABLE_IMAGE の場合に NRTrackableImage インスタンスを生成する
    • m_TrackableTypeDict, m_AllTrackables に NRTrackableImage インスタンスを登録する

ここまで読んで、TrackingImageDatabase (ScriptableObject) は何に使われているのか疑問に思いました。 TrackingImageDatabase が関連している処理を探して読んでいくと、NRSessionBehaviour から始まる処理で使用されていることがわかりました。 一連の処理では以下が要点になると思います。

• NRSessionBehaviour
  • NRSessionManager.CreateSession
    • NRDevice.Init
    • NativeInterface.NativeTracking.Create
      • NativeApi.NRTrackingCreate(ref m_TrackingHandle)
      • NativeInterface.TrackingHandle = m_TrackingHandle
    • NativeAPI.NativeTracking.SetTrackingMode(TrackingMode)
    • DeployData
      • database = SessionConfig.TrackingImageDatabase
      • ZipUtility.UnzipFile(database.RawData, database.TrackingImageDataOutPutPath, NativeConstants.ZipKey)
        • TrackingImageDataOutPutPath は [Application.persistentDataPath]/TrackingImageData/
  • NRSessionManager.StartSession
    • SetAppSettings(SessionConfig.OptimizedRendering)
    • NativeAPI.NativeTracking.Start()
      • NativeApi.NRTrackingStart
    • NativeAPI.NativeHeadTracking.Create()
      • NativeApi.NRHeadTrackingCreate
  • NRSessionManager.SetConfiguration
    • NativeConfigration.UpdateConfig
      • NativeApi.NRConfigCreate(m_NativeInterface.TrackingHandle, ref m_ConfigHandle)
        • m_ConfigHandle が 0 の場合のみ行う
      • NRSessionConfig.ImageTrackingMode が DISABLE の場合
        • NativeTrackableImage.DestroyDataBase(m_DatabaseHandle)
          • m_DatabaseHandle が 0 以外の場合のみ行う
      • NRSessionConfig.ImageTrackingMode が ENABLE の場合
        • m_DatabaseHandle = NativeTrackableImage.CreateDataBase()
        • NativeTrackableImage.LoadDataBase(m_DatabaseHandle, TrackingImageDataPath)
          • TrackingImageDataPath : NRSessionConfig.TrackingImageDatabase.TrackingImageDataPath
            • [Application.persistentDataPath]/TrackingImageData/[DB_GUID] ディレクトリ
        • NativeApi.NRConfigSetTrackableImageDatabase(m_NativeInterface.TrackingHandle, m_ConfigHandle, m_DatabaseHandle)

要点を整理する

NRFrame.GetTrackable

NRFrame.GetTrackable の API は以下の様になっており、引数 trackables には検出した結果を格納する List、引数 filter には結果を絞り込む条件を指定します。

void NRFrame.GetTrackable<T>(List<T> trackables, NRTrackableQueryFilter filter) where T : NRTrackable

NRTrackableQueryFilter は All と New の 2 種類です。 NRTrackable のサブクラスは NRTrackableImage と NRTrackablePlane があり、T にはいずれかを指定します。

NRFrame.GetTrackable では、NRTrackableManager.GetTrackables を呼び出しています。引数は NRFrame.GetTrackables と同じです。 NRTrackableManager.GetTrackables では以下を行います。

• NRTrackableManager.UpdateTrackables を呼び出して AllTrackables (List<NRTrackable>) を更新する
• AllTrackables に新しく追加された NRTrackable を NewTrackables (List<NRTrackable>) に格納する
• filter が All であれば AllTrackables の NRTrackable を trackables に格納する
• filter が New であれば NewTrackables の NRTrackable を trackables に格納する

NRTrackableManager.UpdateTrackables では、Native API を呼び出して AllTrackables を更新します。 UpdateTrackables の引数には TrackableType が渡されます。 TrackableType は型パラメータの T から決定されます。 T が NRTrackableImage の場合は TrackableType は TRACKABLE_IMAGE、T が NRTrackablePlane の場合は TrackableType は TRACKABLE_PLANE になります。

NRTrackableManager.UpdateTrackables は以下の疑似コードの様に Native API を呼び出します。

void UpdateTrackables(TrackableType trackable_type)
{
    UInt64 trackable_list_handle;
    int list_size;
    NRTrackableListCreate(session_handle, ref trackable_list_handle);
    NRTrackingUpdateTrackables(session_handle, trackable_type, trackable_list_handle);
    NRTrackableListGetSize(session_handle, trackable_list_handle, ref list_size);
    for (int index = 0; index < list_size; index++)
    {
        UInt64 trackable_handle;
        TrackableType out_trackable_type;
        NRTrackableListAcquireItem(session_handle, trackable_list_handle, index, ref trackable_handle);
        NRTrackableGetType(session_handle, trackable_handle, ref out_trackable_type);
        if (out_trackable_type == TRACKABLE_PLANE) AllTrackables.Add(NRTrackablePlane(trackable_handle));
        if (out_trackable_type == TRACKABLE_IMAGE) AllTrackables.Add(NRTrackableImage(trackable_handle));
    }
    NRTrackableListDestroy(session_handle, trackable_list_handle);
}

上記のコードにおいて、session_handle は NativeInterface.TrackingHandle です。 NativeInterface.TrackingHandle は NRSessionManager.CreateSession の過程で設定されます。 これについては後ほど説明します。

以上で、NRFrame.GetTrackable から始まる一連の処理は終了です。 Native API を使用して ImageTracking を行っていることが分かります。

ImageTracking に関連する初期化処理

ここまで TrackingImageDatabase (ScriptableObject) は全く登場しませんでした。 ImageTracking には不要なのでしょうか？ これについては NRSessionManager の Awake, Start の処理を見ていくことで理解が深まります。

NRSessionManager の Awake, Start では NRSessionManager の CreateSession, StartSession, SetConfiguration を呼び出しています。 これらの過程では以下に示す ImageTracking に関連する初期化処理が行われています。

• NativeInterface.TrackingHandle の初期化

TrackingHandle の値は Native API から取得されます。 疑似コードで示すと以下の様になります。

UInt64 tracking_handle;
NRTrackingCreate(ref tracking_handle);
NativeInterface.TrackingHandle = tracking_handle;

• TrackingImageDatabase データの展開

TrackingImageDatabase データは SessionConfig.TrackingImageDatabase.RawData に byte[] として保持しています。 この RawData は zip アーカイブのデータになっており、unzip して [Application.persistentDataPath]/TrackingImageData/ に展開されます。

• ImageTracking の有効化/無効化

SessionConfig.ImageTrackingMode が ENABLE の場合には ImageTracking を以下の疑似コードの処理で有効化します。 session_handle は NativeInterface.TrackingHandle で、trackable_image_database_directory は SessionConfig.TrackingImageDatabase.TrackingImageDataPath です。 TrackingImageDataPath は [Application.persistentDataPath]/TrackingImageData/[DB_GUID]/ です。

UInt64 config_handle;
UInt64 trackable_image_database_handle;
NRConfigCreate(session_handle, ref config_handle);
NRTrackableImageDatabaseCreate(session_handle, ref trackable_image_database_handle);
NRTrackableImageDatabaseLoadDirectory(session_handle, trackable_image_database_handle, trackable_image_database_directory);
NRConfigSetTrackableImageDatabase(session_handle, config_handle, trackable_image_database_handle);

SessionConfig.ImageTrackingMode が DISABLE の場合には ImageTracking を以下の疑似コードの処理で無効化します。 session_handle は NativeInterface.TrackingHandle で、trackable_image_database_handle は有効化した時の値、trackable_image_database_handle は 0 です。

UInt64 config_handle;
NRConfigCreate(session_handle, ref config_handle);
NRTrackableImageDatabaseDestroy(session_handle, trackable_image_database_handle);
NRConfigSetTrackableImageDatabase(session_handle, config_handle, trackable_image_database_handle);

以上で、初期化処理は終了です。TrackingImageDatabase のデータは RawData に保持しており、unzip した上で Load しています。

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
  • IntPtr android_activity

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

  • UInt64 rendering_handle
  • IntPtr android_surface

• 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 < 1m²
     • 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

• RGBCamera-Record (Scene)
  • NRCameraRig (Perfab)
    • こちらを参照
  • NRInput (Prefab)
    • こちらを参照
  • NRLogo (Prefab)
    • こちらを参照
  • Directional Light : 上から差し込むライト
    • [C] Light
  • VideoCaptureExample
    • [C] VideoCapture2LocalExample
    • Previewer (Prefab)
      • こちらを参照
  • PlaneDetector
    • [C] PlaneDetector
    • [C] HelloMRController
  • Canvas
    • [C] Canvas
    • [C] Canvas Scaler
    • [C] CanvasRaycastTarget
    • Panel
      • [C] Image
      • startBtn
        • [C] Image
        • [C] Button
        • Text
          • [C] Text
      • stopBtn
        • [C] Image
        • [C] Button
        • Text
          • [C] Text

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)

  • NRCameraRig (Perfab)
    • こちらを参照
  • NRInput (Prefab)
    • こちらを参照
  • NRLogo (Prefab)
    • [C] AutoRotate : Mesh を回転させる
    • offset
      • nreal_logo
        • [C] Mesh Renderer
  • PhotoCaptureExample
    • [C] PhotoCaptureExample
    • Previewer (Prefab)
  • Directional Light : 上から差し込むライト
    • [C] Light

• 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 と同様に Hierarchy と Scripts を網羅したいところですが、内容に重複する部分が多いため重複部分は省略します。

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)
    • こちらを参照
    • [C] NRInput
      • Override Camera Center に CenterCamera が設定されている
        • デフォルトは None
  • 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 に設定された Canvas は NRPointerRaycaster で 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 には記載がないクラス)