Instalando o software libfreenect na sua plataforma

Esse artigo mostra como preparar sua plataforma para começar a desenvolver com o OpenKinect. Veremos como instalar as bibliotecas necessárias para o desenvolvimento nas plataformas Linux, MacOSX e Windows, além de informações básicas para a codificação de seus projetos.

O adaptador

O Kinect precisa de uma fonte de energia própria que é independente da conexão USB para funcionar em um computador. O XBOX 360 mais recente pode fornecer energia ao Kinect diretamente mas os mais antigos requerem um adaptador para esse propósito. Assim, o Kinect que é vendido junto com o XBOX 360 não inclui um adaptador, enquanto que o Kinect que é vendido separadamente acompanha o adaptador. O adaptador pode ser encontrado a venda aqui. Esse adaptador é necessário para usar o Kinect em seu compurador com a libfreenect.

Fakenect

É também possível usar o utilitário Fakenect, que é um simulador do freenect para rodar demos do Kinect sem ter um Kinect.

Linux

Pacotes binários

Pacotes rpm e deb já compilados podem ser encontrados aqui: http://livingplace.informatik.haw-hamburg.de/blog/?p=228

Observe que não existem dispositivos gerados pelo udev por enquanto, então você pecisa executar seus programas como root (use o sudo).

Ubuntu

Um ppa para o Ubuntu tanto para a versão Lucid (10.04) e Maverick (10.10) está disponível em:

https://launchpad.net/~arne-alamut/+archive/freenect

para usa-lo, abra um console e execute o comando:

$ sudo add-apt-repository ppa:arne-alamut/freenect

Re-sincronize a lista de pacotes dos repositórios:

$ sudo apt-get update

Depois disso, você poderá usar o comando:

$ sudo apt-get install freenect

Isso instalará os arquivos libfreenect.o, libfreenect-demos e libfreenect-dev.

Depois disso, você precisará adicionar você mesmo no grupo ‘video’ e logar novamente. O pacote já inclui as regras necessárias para o daemon udev assim os acesso ao dispositivo será possivel para usuários do grupo ‘video’.

$ sudo adduser YOURNAME video

certifique-se de sair do sistema e voltar. Você não precisa reiniciar o computador, só conecte o dispositivo kinect agora (Se já estiver conectado, desconecte e conecte de novo).

Para iniciar as aplicações demo use:

$ freenect-glview

Todas as aplicações demo são iniciadas com o prefixo freenect-.

Instalação manual no Ubuntu

Abaixo segue as instruções de instalação para copiar e colar rapidamente:

sudo apt-get install git-core cmake libglut3-dev pkg-config build-essential libxmu-dev libxi-dev libusb-1.0-0-dev
git clone https://github.com/OpenKinect/libfreenect.git
cd libfreenect
mkdir build
cd build
cmake ..
make
sudo make install
sudo ldconfig /usr/local/lib64/
sudo glview

Essas instruções devem ser uma das maneiras mais rápidas de fazer o Kinect rodar no Ubuntu. Um passo recomendado seria esse:

sudo adduser YOURNAME video
cat << EOF >> /etc/udev/rules.d/51-kinect.rules
# ATTR{product}=="Xbox NUI Motor"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02b0", MODE="0666"
# ATTR{product}=="Xbox NUI Audio"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02ad", MODE="0666"
# ATTR{product}=="Xbox NUI Camera"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02ae", MODE="0666"
EOF

Compilação manual no Linux

essas instruções requeremmais trabalho, a maior parte coberta pelo arquivo README.asciidoc

Instalação das dependências

Para compilar os fontes, você precisa ter as seguintes bibliotecas instaladas:

* cmake
* libusb-1.0-0
* libusb-1.0-0-dev
* pkg-config
* libglut3
* libglut3-dev

Note que os nomes de pacotes acima parecem ser orientados para Ubuntu?Debian. Para uma instalação do RedHat/Fedora usando yum/rpms, o comando abaixo deve instalar todos os pacotes necessários para compilar e rodas o glview:

$ yum install git cmake gcc gcc-c++ libusb1 libusb1-devel libXi libXi-devel libXmu libXmu-devel freeglut freeglut-devel

usuários do APT (funciona no ubuntu 10.10):

$ sudo apt-get install cmake libglut3-dev pkg-config build-essential libxmu-dev libxi-dev libusb-1.0-0-dev

Clone o repositório

$ git clone https://github.com/OpenKinect/libfreenect.git
$ cd libfreenect

cmake

$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install
$ sudo ldconfig /usr/local/lib64/

Erros

Se você verificar o seguinte erro na execução do cmake:

$ CMake Error: The following variables are used in this project, but they are set to NOTFOUND.
$ Please set them or make sure they are set and tested correctly in the CMake files:
$ GLUT_Xi_LIBRARY (ADVANCED)
$    linked by target "glview" in directory /home/user/libfreenect/examples
$ GLUT_Xmu_LIBRARY (ADVANCED)
$    linked by target "glview" in directory /home/user/libfreenect/examples

Então você precisa instalar libxi-dev e libxmu-dev/libxmu-headers. Se estiver usando Ubuntu 10.04, digite o comando: sudo apt-get install libusb-1.0-0-dev libxmu-dev libxi-dev.

No caso do glview emitir um erro relacionado a biblioteca compartilhada (shared):

$ glview
glview: error while loading shared libraries: libfreenect.so.0.0: cannot open shared object file: No such file or directory

Você precisará atualizar o cache do ldconfig:

$ sudo ldconfig /usr/local/lib64/

esse comando depende naturalmente de onde  você instalou as suas bibliotecas.

Python

Para compilar os empacotadores Python você precisará do pacote ‘python-dev’ e cython. O pacote cython incluido no Ubuntu 10.10 pareçe estar quebrado, então obtenha o pacote disponível aqui.

 $ sudo easy_install cython

Uso como usuário normal

Para ser capaz de acessar o Kinect você precisa adicionar seu usuário no grupo ‘video’ e alterar a permissão do dispositivo criado.

crie um arquivo /etc/udev/rules.d/66-kinect.rules

#Rules for Kinect ####################################################
SYSFS{idVendor}=="045e", SYSFS{idProduct}=="02ae", MODE="0660",GROUP="video"
SYSFS{idVendor}=="045e", SYSFS{idProduct}=="02ad", MODE="0660",GROUP="video"
SYSFS{idVendor}=="045e", SYSFS{idProduct}=="02b0", MODE="0660",GROUP="video"
### END #############################################################

e adicione seu usuário ao grupo ‘video’:

$ sudo adduser YOURNAME video

Testando o Kinect

Você precisa fazer isso como root (ou usando o comando sudo) se não seguiu os passos da seção anterior.

$ bin/glview

ou

$ sudo bin/glview

OS X

É melhor instalar por um gerenciador de pacotes. Se não possuir macports ou fink, tente o Homebrew, pois está disponível um pacote completo para essa plataforma.

MacPorts

Versões atuais do MacPorts precisam do suporte de diversas versões diferentes da libusb. Existe uma versão especial do libusb-devel compilado com os patches necessários para o Kinect.

Depois de instalar MacPorts, execute os comandos:

 sudo port install git-core
 sudo port install libtool
 sudo port install libusb-devel

Depois altere o diretório de trabalho, e você poderá executar:

git clone https://github.com/OpenKinect/libfreenect.git

use “git clone git://github.com/OpenKinect/libfreenect.git” se você frequentemente receber a mensagem de erro ‘Segmentation fault’!

e siga para a seção “Compilação manual no OSX”. A libusb encontrada pelo cmake estará correta e patcheada, simplificando o processo de compilação!

Fink

Depois de instalar o Fink, execute os comandos abaixo. Primeiro, configure o Fink para compilar os pacotes do reporitório unstable, assim você poderá obter a última versão do libusb:

 fink configure

Depois, instale as dependência do freenect:

 fink install cmake git libusb1

Por fim, altere o diretório de trabalho e execute o seguinte comando:

git clone https://github.com/OpenKinect/libfreenect.git

agora é só seguir os passos da seção “Compilação manual no OSX”.

Homebrew

If you dont have Homebrew already, it is quite simple to install.

Se não possui o Homebrew, instale seguindo os passos descritos aqui.

Observação: Mesmo que você já tenho o Homebrew instalado, certifique-se de atualizar suas formulas (execute ‘brew update’), antes de tentar instalar o libfreenect.

Obtenha as fórmulas

Como o fluxo de pacotes do projeto é muito grande, muitos podem não estar no diretório do homebrew, assim você precisará busca-los manualmente:

cd /usr/local/Library/Formula
curl --insecure -O "https://github.com/OpenKinect/libfreenect/raw/master/platform/osx/homebrew/libfreenect.rb"
curl --insecure -O "https://github.com/OpenKinect/libfreenect/raw/master/platform/osx/homebrew/libusb-freenect.rb"

Instalação

brew install libfreenect

E depois disso, o processo está finalizado! Uma cópia do glview deve estar agora em seu PATH, de modo que você pode simplesmente executar:

glview

para confirmar que tudo está funcionando corretamente.

Compilação manual no OSX

Pré-requisitos:

Crie a ligação entre o repositório do OpenKinect e o libusb:

git clone https://github.com/OpenKinect/libfreenect.git
git clone git://git.libusb.org/libusb.git or git clone http://git.libusb.org/libusb.git

Você não precisa executar esse último passo se já instalou o libusb-devel via MacPorts. Se você clonou libusb via github, precisará fazer o patch para que a biblioteca funcione com o OpenKinect:

cd libusb
./autogen.sh
patch -p1 < ../libfreenect/platform/osx/libusb-osx-kinect.diff
./configure LDFLAGS='-framework IOKit -framework CoreFoundation'
make
sudo make install

agora instale o OpenKinect:

cd ../libfreenect/
mkdir build
cd build
ccmake ..

Não se preocupe se a mensagem “Empty Cache” for exibida no final. Agora pressione ‘c’ no ccmake para configura-lo. Se já tiver instalado o libusb via MacPorts ou Homebrew, tudo funcionará sem problemas. De outra forma, irá dar um erro, por não conseguir encontrar o libusb. Pressione ‘e’ para sair da ajuda e editar manualmente o caminho para a biblioteca libusb para o valor ‘/usr/local/include/libusb-1.0/’ e continue.

Quando terminar, compile o OpenKinect:

cmake ..
make

Se quiser compilar como um projeto do Xcode, use os comandos abaixo:

cmake -G Xcode ..
make

E agora está terminado! Deve existir um programa chamado ‘glview’ em libfreenect/build/bin. Comecte o sei Kinect e começe a trabalhar. Se a mensagem ‘ld: warning: in /usr/local/lib/libusb-1.0.dylib, missing required architecture x86_64’ for exibida quando estiver executando o comando make, você terá que corrigir os caminhos utilizados pelo cmake: eles tem que apontar para /opt… quando a libusb foi instalada como o MacPorts.

Para que os arquivos estejam disponíveis globalmente no seu Mac e possa utiliza-los em seus próprios projetos, você tem que instala-los:

sudo make install

Uso com pyusb

Se você também quiser usar a pyusb para desenvolver com o Kinect, precisará da libusb-1.0.8. Instale ela pelo Homebrew e defina a variavel _lib antes de procurar pelo dispositivo usb:

from ctypes import *
import usb.core
import usb.utils

_lib = CDLL('/usr/local/Cellar/libusb/1.0.8/lib/libusb-1.0.dylib') # That's the location homebrew puts the libusb libraries
dev = usb.core.find(idVendor=0x045e, idProduct=0x02B0)

Windows

Se você estiver procurando por uma mostra de projetos antes de compilar, deve dar uma olhada no demo precompilado (o código também está disponível) que usa libfreenect e opencv.

Compilação manual a partir do código fonte

Introdução

A compilação a partir do código não deve requerer nenhuma experiência específica mas ainda deve ser um pouco desafiadora. Essa introdução serve para lhe fornecer açgumas dicas que você precisará para o processo. Para resumir a história, você irá baixar a última versão do libfreenect e as dependência em separado. As dependência serão usadas em dobro. Primeiro, você copiará os arquivos dll para seu sistema em um local onde eles poderão ser acessados. Depois, você criará ligará os arquivos lib e os arquivos de cabeçalho  ao código fonte usando um programa gráfico do cmake, para que possa configurar o projeto e gerar os makefiles necessários para a compilação.

Finalmente, você puxará o projeto configurado para seu ambiente de desenvolvimento (ex Visual Studio) para compilar os arquivos ou iniciar seu  projeto. O que você deve entender disso tudo é que seu sistema precisa de algumas bibliotecas para rodar os demos do projeto como qualquer outra peça de software (os arquivos dll são usados para isso) e que antes de tudo você precisa definir onde estão as bibliotecas e arquivos de cabeçalho para que a compilação ocorra sem erros. Observe que o resultado da compilação do libfreenect é um arquivo  dll que sua máquina precisa acessae para poder executar o glview, entre outras coisas. Tudo isso ficará claro no decorrer do passo-a-passo.

Obtendo os arquivos do código fonte

Existem duas maneiras para obter o código fonte:

  1. Vá até o github do projeto OpenKinect, selecione o tipo que você quer (master ou unstable, por exemplo) e clique em “Download” ( depois extraia os arquivos em um local conveniente) ou
  2. Usar o Git para criar e manter um pasta atualizada para o projeto e acessar qualquer um dos tipos localmente:

Usando o Git

  • Baixe e instale o Git com essas configurações:
    • Aceite a licença e etc.
    • Escolha o nível de integração shell que você quer
    • Escolha “Run git from the Windows Command prompt”
    • Escolha “Check out WIndows style, commit Unix-style line endings”
  • Abra o prompt de comando, vá até o diretório onde você quer instalar o código fonte (/libfreenect) que você criou e digite:
$ git clone https://github.com/OpenKinect/libfreenect.git //downloads the project, creates local master
$ cd libfreenect                                            //cd to source directory
$ git branch --track unstable origin/unstable        //creates a local unstable branch for remote unstable
$ git checkout master                                //check out the master or unstable branch
$ or
$ git checkout unstable
$ git pull                                           //updates the contents of the selected branch
  • O conteúdo da pasta libfreenect será alterada interativamente toda vez que der um checkout em um tipo específico, assim você não precisará buscar um “tipo” específico dentro da pasta libfreenect. Só dê um checkout no tipo que você quer configurar para compilar e continue usando a pasta libfreenect como fonte do cmake. Essa configuração permite que você facilmente troque entre os tipos master e unstable, atualize os arquivos e configure o tipo que você quer compilar.
  • O comando “git branch” mostrará a você os tipos diferentes (no nosso caso, master e unstable) e quais estão atualmente selecionados. Você pode ver também os logs do desenvolvimento de cada tipo que estiver checando com o comando “git log” (use shift-Q para sair da exibição do log).

Tipo Master vs Unstable

Se você estiver planejando modificar a libfreenect, escrever invólucros ou testar os últimos desenvolvimentos, você irá quer checar o tipo Unstable. Esse tipo é onde ficam os últimos commits que ainda não foram testados. Se não for o seu caso, use o master.

  • Observe que tanto o master quanto o unstable foram atualizados em 06/01/11; veja esse texto para mais informações;
  • Em 15/02, o suporte para múltiplas resoluções foi adicionado ao unstable e o 1280×1024 RGB e modo infra-vermelho foi ativado como explicado aqui.

Depois que você tiver obtido o código fonte, você deve baixar as dependências necessárias para configurar e compilar a biblioteca e então instalar o driver do hardware.

Dependências

Para cada dependência necessária, primeiro baixe e instale a biblioteca (.dll) em seu sistema e depois identifique o caminho para as bibliotecad (.lib ou .a) e arquivos de cabeçalho (.h) que você precisará para compilar o código com o cmake:

Dependency Install Library/includes to be used with cmake
libusb-win32 – download and extract the latest libusb-win32-bin-x.x.x.x.zip This will be taken care of when we install the driver in the next section The /lib and /include folders contain the libraries and header files required to configure the project; depending on the compiler you choose, you may have to specify a different library file:

  • For instance, to configure for MS Visual Studio 2010, use /lib/msvc/libusb.lib or if you plan to use mingw, use /lib/gcc/libusb.a as the libusb library path in cmake (LIBUSB_1_LIBRARY)
  • Select the path to the libusb header folder /include as libusb include path in cmake (LIBUSB_1_INCLUDE_DIR)

For more info see the libusb-win32 readme and their wiki

pthreads-win32 – download and extract the latest pthreads-w32-x-x-x-release.exe Find the /lib folder and copy the appropriate .dll library to /windows or /windows/system32 (see Library/includes to the right to figure out which one to use) The /lib and /include contain the libraries and header files required to configure the project; depending on the compiler you choose, you may have to specify a different library file:

  • For instance, to configure for MS Visual Studio 2010, use /lib/pthreadVC2.lib or if you plan to use mingw, use /lib/pthreadGC2.a as the pthread library path in cmake (THREADS_PTHREADS_WIN32_LIBRARY)
  • In both cases you will need to install the corresponding library .dll file to /windows/system32 i.e. phtreadVC2.dll or pthreadGC2.dll
  • Select the path to the pthread header folder /include as pthread include path in cmake (THREADS_PTHREADS_INCLUDE_DIR)

For more info see the pthreads-win32 readme and their FAQ

Glut – download and extract the latest glut-x.x.x-bin.zip Find the glut32.dll file and copy it to /windows/system or any directory included in your PATH system variable (see this explanation)
  • With MSVC, you should copy the glut.h header file to the /include/GL folder and the glut32.lib library to the /lib folder of your VC tree(for instance /Program Files/Microsoft Visual Studio 10.0/VC/) – if the GL folder is not there, create it and put the glut.h file there. If you built glut from source, the files should already be there.
  • In cmake-gui, supply the path to the header up to the /include folder (NOT ../include/GL) and the path to the library itself (../lib/glut32.lib) in cmake (GLUT_INCLUDE_DIR and GLUT_glut_LIBRARY respectively)

For more info see the glut readme

Instalação do driver

Existem duas partes do libfreenect – o driver de baixo nível baseado no libusb e o próprio libfreenect,  a biblioteca que conversa com o driver. Você precisa instalar o driver uma única vez.

Windows 7: passo-a-passo (que deve funcionar no Windows Xp também)

  • Conecte o Kinect ao computador. O Windows avisará que nenhuma driver de dispositivo foi encontrado para o dispositivo plugado (O LED doKinect não ligará). Se o Windows apresentar uma caixa de diálogo solicitando a pesquisa por drivers, simplesmente cancele-a.
  • Abra o Gerenciados de dispositivo: Iniciar >> Painel de controle >> Sistema e segurança >> Sistema >> Gerenciador de dispositivos
  • Um dispositivo chamado “Xbox NUI Motor” deve estar em algum lugar aqui (muito provavelmente em “Outros dispositivos“) com um pequeno simbolo de advertência amarela sobre seu ícone. Clique com o botão direito sobre ele, e selecione “Atualizar Driver…“, e depois clique “Browse my computer for driver software“.
  • Localize e selecioce a pasta onde o arquivo “XBox_NUI_Motor.inf” está localizado (/platform/windows/inf dentro de sua pasta de código fonte libfreenect). Clique “Próximo” e se perguntado pelo Windows se quer instalar um driver não certificado, apenas confirme que quer.
  • Depois disso, o LED do Kinect deve começar a piscar em verde. Agora teremos dois dispositivos adicionais na lista do Gerenciador de dispositivo: “Xbox NUI Camera” and “Xbox NUI Audio“. Repita as instruções acima para eles também.

Você está pronto para compilar o libfreenect agora.

Configurando a instalação com o cmake-gui.

Siga esses passos para configurar e compilar o libfreenect:

  1. Baixe o Cmake e certifique-se de ter um compilador C funcionando (Visual Studio 2010 ou MinGW).
  2. Carregue o Cmake-GUI e selecione sua pasta /libfreenect como fonte, selecione a pasta de saida, marque as opções “advanded” e “grouped” para exibir mais variáveis e categorias e clique no botão “Configure”.
  3. Selecione o compilador C que você quer usar
  4. Selecione as opções de BUILD que você quer, levando em consideração o seguinte:
    1. No momento, selecione opções EXAMPLES e C_SYNC em BUILD. As outras opções como FAKENECT ainda não foram atualizadas para o Visual Studio
    2. Dê uma olhada nas notas de compilação do Python se estiver interessado em compilar esses recurso
  5. Dependências não resolvidas serão mostradas em vermelho na Interface. Informe os caminhos ausentes para essas dependências e clique no botão “Configure” novamente:
    1. As variáveis *_LIBRARY precisam apontar para arquivos .lib e não para pastas
    2. Variáveis INCLUDE precisam apontar para o diretório correto de arquivos de cabeçalho
  6. Quando todos os erros forem sanados, clique em “Generate” para criar os makefiles que guiarão o compilador.

Compilando

Agora que o projeto foi configurado, abra o arquivo libfreenect.sln na sua pasta de destino com o Visual Studio. Depois verifique seus arquivos compilados em /bin e /lib.

  • As bibliotecas do freenect em /lib estão compiladas mas não instaladas nesse momento. Para poder usá-las, faça o seguinte:
    • Adicione o caminho para a pasta /lib à variável PATH de seu sistema ou
    • Copie as bibliotecas para uma pasta que já esteja no PATH do sistema como em /windows/system32 ou
    • Copie as bibliotecas na pasta do programa que você quer executar
  • Se algum item não compilar, simplesmente dê um clique com o botão direito na solução novamente e selecione “Build” ou “Rebuild” para ver de os itens faltantes são compilados
  • Se encontrar problemas para compilar cheque o readme da pasta /libfreenect/platform/windows para obter mais informações.

Traduzido de http://openkinect.org/wiki/Getting_Started