AzureKinectSDKのサンプルプログラムをPythonの拡張モジュールとしてインストールする その１（拡張モジュールの作成とビルド）

本日は AzureKinectSDK の技術調査枠です。
AzureKinectSDKのサンプルプログラムをPythonの拡張モジュールとしてインストールする一例を記事にします。

今回は拡張モジュールの作成とビルド手順です。

対象とするサンプルプログラム

今回は AzureKinectSDK の sample に含まれる transformation のキャプチャ機能をモジュール化します。
github.com

transformation は AzureKinect のキャプチャや記録データから点群データ(*.ply)ファイルを出力サンプルプログラムです。
今回は本コードを利用して点群データのキャプチャ機能を Python のモジュールとしてインストールします。

必要な環境とファイル

事前に以下のツールのインストールとファイルの取得を行います。
・AzureKinectSDK
・libjpeg-turbo
・AzureKinectSDKのソースコード

以下の記事に従ってツールのインストールを実施します。
bluebirdofoz.hatenablog.com
bluebirdofoz.hatenablog.com
github.com

[Download ZIP]からソースコードがダウンロードできます。
今回、必要となるのは examples/transformation/ 配下のファイルだけです。

拡張モジュール用コードの作成

examples/transformation/ 配下の以下のソースコードを利用します。
・main.cpp
・transformation_helpers.cpp
・transformation_helpers.h
これらを作業用ディレクトリにコピーします。

main.cpp を改変し、以下の kinect_capture.cpp ファイルを作成しました。
main 関数を Python の拡張モジュールとして登録する関数に置き換えています。
・kinect_capture.cpp

クリックで展開

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

#include <k4a/k4a.h>
#include <string>
#include "transformation_helpers.h"
#include "turbojpeg.h"

// Python関連の構造体を利用するため、Python.h をインポート
#include <Python.h>

static bool point_cloud_color_to_depth(k4a_transformation_t transformation_handle,
                                       const k4a_image_t depth_image,
                                       const k4a_image_t color_image,
                                       std::string file_name)
{
    int depth_image_width_pixels = k4a_image_get_width_pixels(depth_image);
    int depth_image_height_pixels = k4a_image_get_height_pixels(depth_image);
    k4a_image_t transformed_color_image = NULL;
    if (K4A_RESULT_SUCCEEDED != k4a_image_create(K4A_IMAGE_FORMAT_COLOR_BGRA32,
                                                 depth_image_width_pixels,
                                                 depth_image_height_pixels,
                                                 depth_image_width_pixels * 4 * (int)sizeof(uint8_t),
                                                 &transformed_color_image))
    {
        printf("Failed to create transformed color image\n");
        return false;
    }

    k4a_image_t point_cloud_image = NULL;
    if (K4A_RESULT_SUCCEEDED != k4a_image_create(K4A_IMAGE_FORMAT_CUSTOM,
                                                 depth_image_width_pixels,
                                                 depth_image_height_pixels,
                                                 depth_image_width_pixels * 3 * (int)sizeof(int16_t),
                                                 &point_cloud_image))
    {
        printf("Failed to create point cloud image\n");
        return false;
    }

    if (K4A_RESULT_SUCCEEDED != k4a_transformation_color_image_to_depth_camera(transformation_handle,
                                                                               depth_image,
                                                                               color_image,
                                                                               transformed_color_image))
    {
        printf("Failed to compute transformed color image\n");
        return false;
    }

    if (K4A_RESULT_SUCCEEDED != k4a_transformation_depth_image_to_point_cloud(transformation_handle,
                                                                              depth_image,
                                                                              K4A_CALIBRATION_TYPE_DEPTH,
                                                                              point_cloud_image))
    {
        printf("Failed to compute point cloud\n");
        return false;
    }

    tranformation_helpers_write_point_cloud(point_cloud_image, transformed_color_image, file_name.c_str());

    k4a_image_release(transformed_color_image);
    k4a_image_release(point_cloud_image);

    return true;
}

static bool point_cloud_depth_to_color(k4a_transformation_t transformation_handle,
                                       const k4a_image_t depth_image,
                                       const k4a_image_t color_image,
                                       std::string file_name)
{
    // transform color image into depth camera geometry
    int color_image_width_pixels = k4a_image_get_width_pixels(color_image);
    int color_image_height_pixels = k4a_image_get_height_pixels(color_image);
    k4a_image_t transformed_depth_image = NULL;
    if (K4A_RESULT_SUCCEEDED != k4a_image_create(K4A_IMAGE_FORMAT_DEPTH16,
                                                 color_image_width_pixels,
                                                 color_image_height_pixels,
                                                 color_image_width_pixels * (int)sizeof(uint16_t),
                                                 &transformed_depth_image))
    {
        printf("Failed to create transformed depth image\n");
        return false;
    }

    k4a_image_t point_cloud_image = NULL;
    if (K4A_RESULT_SUCCEEDED != k4a_image_create(K4A_IMAGE_FORMAT_CUSTOM,
                                                 color_image_width_pixels,
                                                 color_image_height_pixels,
                                                 color_image_width_pixels * 3 * (int)sizeof(int16_t),
                                                 &point_cloud_image))
    {
        printf("Failed to create point cloud image\n");
        return false;
    }

    if (K4A_RESULT_SUCCEEDED !=
        k4a_transformation_depth_image_to_color_camera(transformation_handle, depth_image, transformed_depth_image))
    {
        printf("Failed to compute transformed depth image\n");
        return false;
    }

    if (K4A_RESULT_SUCCEEDED != k4a_transformation_depth_image_to_point_cloud(transformation_handle,
                                                                              transformed_depth_image,
                                                                              K4A_CALIBRATION_TYPE_COLOR,
                                                                              point_cloud_image))
    {
        printf("Failed to compute point cloud\n");
        return false;
    }

    tranformation_helpers_write_point_cloud(point_cloud_image, color_image, file_name.c_str());

    k4a_image_release(transformed_depth_image);
    k4a_image_release(point_cloud_image);

    return true;
}

static int capture(std::string output_dir, uint8_t deviceId = K4A_DEVICE_DEFAULT)
{
    int returnCode = 1;
    k4a_device_t device = NULL;
    const int32_t TIMEOUT_IN_MS = 1000;
    k4a_transformation_t transformation = NULL;
    k4a_transformation_t transformation_color_downscaled = NULL;
    k4a_capture_t capture = NULL;
    std::string file_name = "";
    uint32_t device_count = 0;
    k4a_device_configuration_t config = K4A_DEVICE_CONFIG_INIT_DISABLE_ALL;
    k4a_image_t depth_image = NULL;
    k4a_image_t color_image = NULL;
    k4a_image_t color_image_downscaled = NULL;

    device_count = k4a_device_get_installed_count();

    if (device_count == 0)
    {
        printf("No K4A devices found\n");
        return 0;
    }

    if (K4A_RESULT_SUCCEEDED != k4a_device_open(deviceId, &device))
    {
        printf("Failed to open device\n");
        goto Exit;
    }

    config.color_format = K4A_IMAGE_FORMAT_COLOR_BGRA32;
    config.color_resolution = K4A_COLOR_RESOLUTION_720P;
    config.depth_mode = K4A_DEPTH_MODE_NFOV_UNBINNED;
    config.camera_fps = K4A_FRAMES_PER_SECOND_30;
    config.synchronized_images_only = true; // ensures that depth and color images are both available in the capture

    k4a_calibration_t calibration;
    if (K4A_RESULT_SUCCEEDED !=
        k4a_device_get_calibration(device, config.depth_mode, config.color_resolution, &calibration))
    {
        printf("Failed to get calibration\n");
        goto Exit;
    }

    transformation = k4a_transformation_create(&calibration);

    if (K4A_RESULT_SUCCEEDED != k4a_device_start_cameras(device, &config))
    {
        printf("Failed to start cameras\n");
        goto Exit;
    }

    // Get a capture
    switch (k4a_device_get_capture(device, &capture, TIMEOUT_IN_MS))
    {
    case K4A_WAIT_RESULT_SUCCEEDED:
        break;
    case K4A_WAIT_RESULT_TIMEOUT:
        printf("Timed out waiting for a capture\n");
        goto Exit;
    case K4A_WAIT_RESULT_FAILED:
        printf("Failed to read a capture\n");
        goto Exit;
    }

    // Get a depth image
    depth_image = k4a_capture_get_depth_image(capture);
    if (depth_image == 0)
    {
        printf("Failed to get depth image from capture\n");
        goto Exit;
    }

    // Get a color image
    color_image = k4a_capture_get_color_image(capture);
    if (color_image == 0)
    {
        printf("Failed to get color image from capture\n");
        goto Exit;
    }

    // Compute color point cloud by warping color image into depth camera geometry
#ifdef _WIN32
    file_name = output_dir + "\\color_to_depth.ply";
#else
    file_name = output_dir + "/color_to_depth.ply";
#endif
    if (point_cloud_color_to_depth(transformation, depth_image, color_image, file_name.c_str()) == false)
    {
        goto Exit;
    }

    // Compute color point cloud by warping depth image into color camera geometry
#ifdef _WIN32
    file_name = output_dir + "\\depth_to_color.ply";
#else
    file_name = output_dir + "/depth_to_color.ply";
#endif
    if (point_cloud_depth_to_color(transformation, depth_image, color_image, file_name.c_str()) == false)
    {
        goto Exit;
    }

    // Compute color point cloud by warping depth image into color camera geometry with downscaled color image and
    // downscaled calibration. This example's goal is to show how to configure the calibration and use the
    // transformation API as it is when the user does not need a point cloud from high resolution transformed depth
    // image. The downscaling method here is naively to average binning 2x2 pixels, user should choose their own
    // appropriate downscale method on the color image, this example is only demonstrating the idea. However, no matter
    // what scale you choose to downscale the color image, please keep the aspect ratio unchanged (to ensure the
    // distortion parameters from original calibration can still be used for the downscaled image).
    k4a_calibration_t calibration_color_downscaled;
    memcpy(&calibration_color_downscaled, &calibration, sizeof(k4a_calibration_t));
    calibration_color_downscaled.color_camera_calibration.resolution_width /= 2;
    calibration_color_downscaled.color_camera_calibration.resolution_height /= 2;
    calibration_color_downscaled.color_camera_calibration.intrinsics.parameters.param.cx /= 2;
    calibration_color_downscaled.color_camera_calibration.intrinsics.parameters.param.cy /= 2;
    calibration_color_downscaled.color_camera_calibration.intrinsics.parameters.param.fx /= 2;
    calibration_color_downscaled.color_camera_calibration.intrinsics.parameters.param.fy /= 2;
    transformation_color_downscaled = k4a_transformation_create(&calibration_color_downscaled);
    color_image_downscaled = downscale_image_2x2_binning(color_image);
    if (color_image_downscaled == 0)
    {
        printf("Failed to downscaled color image\n");
        goto Exit;
    }

#ifdef _WIN32
    file_name = output_dir + "\\depth_to_color_downscaled.ply";
#else
    file_name = output_dir + "/depth_to_color_downscaled.ply";
#endif
    if (point_cloud_depth_to_color(transformation_color_downscaled,
                                   depth_image,
                                   color_image_downscaled,
                                   file_name.c_str()) == false)
    {
        goto Exit;
    }

    returnCode = 0;

Exit:
    if (depth_image != NULL)
    {
        k4a_image_release(depth_image);
    }
    if (color_image != NULL)
    {
        k4a_image_release(color_image);
    }
    if (capture != NULL)
    {
        k4a_capture_release(capture);
    }
    if (transformation != NULL)
    {
        k4a_transformation_destroy(transformation);
    }
    if (transformation_color_downscaled != NULL)
    {
        k4a_transformation_destroy(transformation_color_downscaled);
    }
    if (device != NULL)
    {
        k4a_device_close(device);
    }
    return returnCode;
}


// Python から呼び出す関数の定義(Capture)
static PyObject* capture_kinect (PyObject *self, PyObject *args)
{
    // 戻り値を設定す変数を作成する
    int32_t returnCode = 0;
    // 文字列と数値を受け取るための変数を作成する
    // 引数はオプションとし、引数がない場合はデフォルト値を設定する
    const char *p_argstr_dir = ".";
    int p_argi_devieceid = K4A_DEVICE_DEFAULT;
    // 受け取った args を展開する
    // '|'以降のフォーマットはオプションとして扱われる
    if(!PyArg_ParseTuple(args, "|si", &p_argstr_dir, &p_argi_devieceid))
    {
        // 引数の取得に失敗した場合はエラー終了
        return NULL;
    }
    // capture 関数を呼び出す
    returnCode = capture(p_argstr_dir, (uint8_t)p_argi_devieceid);
    // capture 関数の戻り値をそのまま返す
    return PyLong_FromLong(returnCode);
}


// 外部から参照できるメソッドの定義
static PyMethodDef Kinect_capture_Methods[] = {
    // 以下のフォーマットで Python から呼び出すことのできるメソッドを定義する
    // {(参照時の関数名), (C言語内の関数名), (引数の定義), (関数の説明文)}
    // 引数を受け取らない場合は引数の定義に METH_NOARGS を設定する
    {"capture", (PyCFunction)capture_kinect, METH_VARARGS, "capture_kinect description"},
    // 終端を示す
    {NULL, NULL, 0, NULL}
};

//モジュールの定義
static struct PyModuleDef kinect_capture_module = {
    PyModuleDef_HEAD_INIT,     // 固定値(常に PyModuleDef_HEAD_INIT で初期化する)
    "kinecttrans",             // モジュールの名前
    "kinecttrans description", // モジュールの説明文
    -1,                        // メモリ確保の指定(-1は静的な領域を確保しない)
    Kinect_capture_Methods     // メソッドの定義への参照
};

// モジュールの初期化関数
// 初期化関数の関数名は PyInit_(モジュールの名前) とすること
PyMODINIT_FUNC PyInit_kinect_capture (void) {
    // 構造体の初期化やモジュールの作成を行う
    // モジュールの作成
    return PyModule_Create(&kinect_capture_module);
}

これで拡張モジュール kinect_capture を定義する kinect_capture.cpp が作成できました。
更に、作業ディレクトリにビルド設定を記述する setup.py も作成します。

transformation のサンプルを利用する場合、k4a の他、libjpeg-turbo のライブラリの参照を追加する必要があります。
以下の通り、setup.py を記述しました。
・setup.py

from distutils.core import setup, Extension

setup(
    name="kinect_capture",        # モジュールの名前
    version="1.0.0",              # モジュールのバージョン
    author="holomon",             # モジュールの作者
    url="",                       # モジュールのホームページ
    description="description",    # モジュールの説明(help(hello)で確認可能)
    install_requires=[],          # 依存パッケージ([pip install -e .]実行時に一緒にインストール)
    extras_require={
        "develop" : [],           # 拡張依存パッケージ([pip install -e . develop]実行時に一緒にインストール)
    },
    ext_modules=[                 # モジュールのソース
        Extension(
            # モジュールの名前
            'kinect_capture',
            # モジュールの外部参照ライブラリ名
            libraries= ['k4a', 'turbojpeg-static'],
            # モジュールのソースコードファイル名
            sources= ['kinect_capture.cpp', 'transformation_helpers.cpp'])
    ]
)

これでコードの作成は完了しました。
次はビルド環境の準備を進めます。

Includeファイルのコピー

今回のソースコードは k4a/k4a.h と turbojpeg.h のヘッダファイルを参照しています。
最初にこれらのヘッダファイルを Python の include ディレクトリに追加し、参照を追加します。

以下の k4a.h のヘッダファイルを含む k4a ディレクトリを Python 配下の include ディレクトリにコピーします。
・コピー元

C:\Program Files\Azure Kinect SDK v1.3.0\sdk\include\k4a

・コピー先

C:\Users\(ユーザ名)\AppData\Local\Programs\Python\Python37\include

turbojpeg.h のヘッダファイルも同様に Python 配下の include ディレクトリにコピーします。
・コピー元

C:\libjpeg-turbo64\include\turbojpeg.h

・コピー先

C:\Users\(ユーザ名)\AppData\Local\Programs\Python\Python37\include

Libファイルのコピー

次にライブラリファイルを Python の libs ディレクトリに追加し、ライブラリへの参照を追加します。
以下の k4a.lib のライブラリファイルを Python 配下の lib ディレクトリにコピーします。
・コピー元

C:\Program Files\Azure Kinect SDK v1.3.0\sdk\windows-desktop\amd64\release\lib\k4a.lib

・コピー先

C:\Users\(ユーザ名)\AppData\Local\Programs\Python\Python37\libs

turbojpeg のライブラリファイルも同様に Python 配下の libs ディレクトリにコピーします。
turbojpeg-static.lib ファイルがスタティックリンクライブラリになります。
・コピー元

C:\libjpeg-turbo64\lib\turbojpeg-static.lib

・コピー先

C:\Users\(ユーザ名)\AppData\Local\Programs\Python\Python37\libs

kinect_captureのビルド

これで kinect_capture のビルドの準備が整いました。
作業用ディレクトリを開き、右クリックから[PowerShellウィンドウをここに開く]を実行します。

以下のコマンドを実行し、kinect_capture のビルドを実行します。

python .\setup.py build

ビルドが成功すると、build ディレクトリが生成され、kinect_capture.cp37-win_amd64.pyd ファイルが出力されます。
cp37-win_amd64 の部分はビルド環境の情報が反映されます。

これで kinect_capture のビルドは完了です。
次回は kinect_capture のインストールと実行確認を行います。
bluebirdofoz.hatenablog.com