Kameran asetukset

Open Broadcast System -liitän­näi­nen Intel Realsense-kameroille

Base Camp – opis­ke­li­jay­rit­tä­jyy­sa­lus­to­jen kehit­tä­mi­nen -hank­keessa on tavoit­teena pilo­toida erilai­sia etätek­no­lo­gioita mento­roin­nin tukena. Tätä silmällä pitäen aiemmin luotu sovel­lus Intel Real­sense -kame­roi­den video- sekä syvyys­ku­van tallen­ta­mi­seen muun­ne­taan Open Broadcast System (OBS)-liitännäiseksi, jolloin tallen­tei­den teke­mi­nen yksin­ker­tais­tuu. Samalla saadaan aikaan mahdol­li­suus live­strii­mauk­selle. Tässä artik­ke­lissa käyn läpi keskei­sim­piä osa-alueita OBS-liitän­näi­sen kehit­tä­mi­sestä ohjel­mis­to­ke­hit­tä­jän näkökulmasta.

Yleis­kat­saus

Liitän­näi­set (engl. plugins) ovat ohjel­ma­kir­jas­toja, joita käyte­tään toisten ohjel­mien sisällä. Tässä esitelty liitän­näi­nen mahdol­lis­taa RGB- ja syvyys­ku­vien strii­maa­mi­sen tai tallen­ta­mi­sen OBS-ohjel­malla. Liitän­näi­sen luomi­nen vaatii jonkin verran ymmär­rystä Intel Real­sense SDK:sta, sekä OBS-ohjel­man liitän­näis­ten kehittämisestä.

Kehit­tä­mäni liitän­näi­nen koostuu pääosin viidestä tiedostosta.

  • realsense-device.h – alustaa real­sense-kameran, ja käyn­nis­tää datan tallennuksen
  • obs_frame_processor.h/cpp – kameran tallen­ta­mien yksit­täis­ten ruutu­jen käsit­te­ly­lo­giikka. Suodat­ti­met ja syvyy­sar­vo­jen koodaus harmaa­sä­vy­ku­vaksi, RGB- ja syvyys­ku­va­pis­tei­den sijoit­telu rinnakkain.
  • realsense-d400-plugin.cpp – rekis­te­röi liitän­näi­sen OBS-sovellukseen
  • realsense-d400-source.cpp – kytkee OBS-sovel­luk­sen liitän­näi­sen tapah­tu­ma­kut­sut aiem­piin, määrit­tää sovel­luk­sen säätö­ar­vot ja piirtää kuva­pis­te­da­tan liitän­näi­sen tekstuuriin.

Liitän­näi­nen tarvit­see osalta ohjel­mis­to­ke­hyk­set OBS-ohjel­mis­tolle, sekä Real­sense-kame­roille.  Molem­mat ovat avoimen lähde­koo­din ohjel­mis­toja, ja niiden asen­ta­mi­nen on varsin yksin­ker­taista. Liitän­näi­sen kään­tä­mi­nen useam­malle käyt­tö­jär­jes­tel­mälle vaatii alus­ta­koh­tai­set kehitystyökalut.

Liitän­näi­sen ohjel­mal­li­sesta toteutuksesta

Liitän­näi­sen lähde­koo­dissa on monta osaa, jotka kaikki ovat tarpeel­li­sia toimin­nal­li­suu­den ja sen laajen­ta­mi­sen kannalta. Video­ku­van luomi­nen olemassa olevasta pikse­li­da­tasta on ohjel­moitu olen­nai­silta osin realsense-d400-source.cpp-tiedoston funk­tioi­hin realsense_d400_source_update, realsense_d400_source_tick sekä realsense_d400_source_render. Tarkas­tel­laan niiden toimin­nal­li­suutta seuraavaksi.

realsense_d400_source_update luo gs_texture_create-kutsulla sovel­tu­van dynaa­mi­sesti päivi­tet­tä­vän teks­tuu­rin, jos sitä ei ole vielä luotu. Teks­tuu­rilla tarkoi­te­taan näytö­noh­jai­men muis­tissa olevaa kuvaa. Kameran tuot­ta­mat RGB- ja syvyys­ku­vat yhdis­te­tään vierek­käin. Yksit­täi­sen kuvan reso­luu­tio on rajattu 848×480 kuva­pis­tee­seen, joten yhdis­te­tyn kuvan viemä tila on 1696×480 kuvapistettä.

Kaikki grafii­kan päivit­tä­mi­seen tai piir­tä­mi­seen liit­ty­vien operaa­tioi­den on tapah­dut­tava obs_enter_graphics() ja obs_leave_graphics() -funk­tio­kut­su­jen sisällä. Silloin OBS-ohjel­man abstra­hoima alemman tason grafiik­ka­ra­ja­pin­nan piir­to­kon­teksti on käytet­tä­vissä. Tämä liittyy grafiik­ka­ra­ja­pin­to­jen toteu­tuk­seen käyt­tö­jär­jes­tel­missä toimi­vien ikku­noin­ti­jär­jes­tel­mien osalta. Yksin­ker­tais­tet­tuna voimme todeta, että obs_enter_graphics välit­tää grafiik­ka­ra­ja­pin­nalle viestin “nyt OBS-ohjel­man ikku­naan ruve­taan piir­tä­mään”, ja obs_leave_graphics välit­tää viestin ”nyt OBS-ohjel­man ikku­naan piir­tä­mi­nen on päättynyt”.

static void realsense_d400_source_update(void *data, obs_data_t *settings)

{

     struct realsense_d400_source *context = reinterpret_cast<realsense_d400_source*>(data);

    obs_enter_graphics();

    if ( context->texture == nullptr )

    {

     …

      context->texture = gs_texture_create( 848*2, 480, GS_RGBA, 1, nullptr, GS_DYNAMIC);

    }

    obs_leave_graphics();

}

realsense_d400_source_tick puoles­taan päivit­tää jokai­sen ruudun­päi­vi­tyk­sen yhtey­dessä video­teks­tuu­rin keskus­muis­tiin tallen­ne­tusta kuva­da­tasta gs_texture_set_image-funk­tio­kut­sun avulla. frame_processor-olio käsit­te­lee kame­rasta tallen­ne­tut kuva­tie­dot, ja muodos­taa niistä sovel­tu­van esityk­sen hyödyn­net­tä­väksi teks­tuu­rissa. Tässä yhtey­dessä on hyvä muistaa, että koneen väylä­no­peu­della on osit­tain merki­tystä teks­tuu­rien päivi­tys­no­peu­teen, koska tiedon on siir­ryt­tävä keskus­muis­tista näytö­noh­jai­men muistiin.

static void realsense_d400_source_tick(void *data, float seconds)

{

  struct realsense_d400_source *context = reinterpret_cast<realsense_d400_source*>(data);

  …

      const uint8_t *tmp = context->frame_processor.tmp_data.data();

      obs_enter_graphics();

      gs_texture_set_image( context->texture,

                            context->frame_processor.tmp_data.data(),

                            848*2*4, false);

       obs_leave_graphics();

  …

}

realsense_d400_source_render –funktio piirtää päivi­te­tyn video­teks­tuu­rin ruudulle. Funk­tiossa sido­taan teks­tuuri muodos­tet­ta­vaan kuvaan, sekä piir­re­tään teks­tuuri ruudulle.

 static void realsense_d400_source_render(void *data, gs_effect_t *effect)

{

  struct realsense_d400_source *context = reinterpret_cast<realsense_d400_source*>(data);

  obs_enter_graphics();

  gs_eparam_t *image = gs_effect_get_param_by_name(effect, ”image”);

  gs_effect_set_texture(image, context->texture);

  gs_draw_sprite(context->texture, 0, context->frame_processor.video_width,

                 context->frame_processor.video_height );

  obs_leave_graphics();

}

Loput liitän­näi­sen toimin­nal­li­suu­desta liit­ty­vät lähes yksi­no­maan Intel Real­sense SDK:n asetus­ten säätä­mi­seen, sekä kame­rasta saapu­vien kuvien käsit­te­lyn säikeis­tä­mi­seen, mutta näiden toimin­nan avaa­mi­nen on varsi­nai­sen liitän­näi­sen teke­mi­sen ulko­puo­lella. Lisä­tie­toja näistä on saata­villa Realsense2 SDK:n koodie­si­mer­keissä.

Liitän­näi­sen asentaminen

Liitän­näi­sen asen­ta­mi­nen vaatii liitän­näi­sen kirjas­to­tie­dos­ton siir­tä­mi­sen OBS-ohjel­mis­ton liitän­näis­ten hake­mis­toon real­sen­se2-kirjas­to­tie­dos­ton kanssa. Esimer­kiksi käyt­tä­mäl­läni koneella OBS-ohjelma on asen­nettu hake­mis­toon C:\Tools\obs-studio, jolloin realsense2.dll ja realsense-d400-plugin.dll kopioi­daan hake­mis­toon C:\Tools\obs-studio\obs-plugins\64bit. Lisäksi liitän­näi­selle tehdään tyhjä loka­li­soin­ti­tie­dosto en-US.ini hake­mis­toon C:\Tools\obs-studio\data\obs-plugins\realsense-d400\locale.

Liitän­näi­sen käyttöönotto

Mikäli kaikki liitän­näi­sen tiedos­tot on asen­nettu ja Real­sense-kamera kytketty konee­seen, OBSissa on mahdol­lista lisätä kuva­läh­teeksi useam­pi­kin Real­sense D400 Input (Kuva 1). Sen jälkeen kuva­läh­teen asetuk­sista puoles­taan on valit­ta­vissa jokin kytke­tyistä kame­roista käyt­töön (Kuva 2).

OBS-ohjelman näkymä
Kuva 1. OBS-ohjel­man näkymä, johon on liitetty neljä kameraa. Kuvat on kään­netty 90 astetta vasta­päi­vään. Kuva­läh­teeksi valitun kameran kuva on koros­tettu punai­sella reunuksella. 
Kameran asetukset
Kuva 2. Valitun kameran asetuk­set. Tällä hetkellä säädet­tä­vissä on ylä- ja alara­jat tallen­net­ta­ville syvyy­sar­voille, sekä syvyys­ku­van arvon suhde reaa­li­maa­il­maan (yksi yksikkö vastaa 100 mikro­met­riä, eli 0.1 millimetriä).

Liitän­näi­nen on julkaistu GPLv3-lisens­sillä Github-verk­ko­pal­ve­luun. Liitän­näistä hyödyn­ne­tään jatkossa Basecamp-hank­keen etätek­no­lo­gia­ko­kei­luissa, kun inten­sii­vi­val­men­nuk­sista luodaan virtuaalihologrammeja.


Kirjoit­taja:

Anssi Gröhn, tieto­jen­kä­sit­te­lyn lehtori, Basecamp-hank­keen asian­tun­tija, Karelia-ammattikorkeakoulu