Introduction and Overview

Este documento contém instruções para instalar e migrar para a última versão do OpenCV (versão 3) e para os bindings Python. Além de algumas alterações na API, há também alterações na interface Python (por exemplo, remoção de cv2.cv) que podem requerer alterações no código existente para funcionar com a nova versão do módulo cv2. Após a instalação, veja a próxima página, Migração & Alterações, para detalhes sobre as alterações no módulo e para ajuda na migração do código Python existente para a nova versão.

Esta página cobre a instalação do OpenCV 3 no Windows (usando binários pré-construídos) e Linux (compilado a partir do código fonte), incluindo a interface Python (o módulo cv2). OpenCV pode ser baixado a partir do site oficial do OpenCV. Note que este guia foi escrito com base na versão 3.1.0 do OpenCV. Após a instalação, é recomendado que você possa verificar a versão do OpenCV que o Python está usando:

import cv2print cv2.__version__# Should print 3.0.0-rc1 or newer.

Note que embora o OpenCV 3 seja o último lançamento, por convenção, o módulo ainda se chama cv2.

Instalando no Windows (binários pré-construídos)

Usar binários pré-construídos é a maneira mais rápida de ter um ambiente OpenCV Python em funcionamento no Windows. Atualmente, apenas a versão Python 2 do módulo cv2 está compilada e incluída na última versão do Windows. O suporte ao Python 3 (assim como a adição de outros recursos/módulos não-padrão), requer compilação a partir do código fonte – veja a documentação oficial do OpenCV para detalhes.

Downloading OpenCV and Python

Para começar, baixe o OpenCV for Windows (versão 3.1, opencv-3.1.0.exe), e extraia-o para um diretório de sua escolha. A compilação do Windows inclui um módulo de 32 e 64 bits para Python 2.7.

Antes de continuar, certifique-se de que você tem uma instalação do Python 2.7 funcionando, que pode ser baixada do site do Python. Este guia foi testado usando o Python 2.7.9 (x86 installer / x64 installer). Ao instalar, é recomendado que você permita ao instalador adicionar o Python à sua variável de ambiente PATH, para que você possa executar python e pip a partir de um prompt de comando.

Installing Module Dependencies

The Python OpenCV cv2 module requires both the NumPy and SciPy stack. Para obter isto, primeiro certifique-se de que você tem um ambiente python funcional, e tem pip instalado (se não, use os links acima, e certifique-se de que a pasta Python está na sua variável PATH).

Christoph Gohlke atualmente fornece alguns pacotes Python pré-construídos (não-oficiais) para Windows, incluindo NumPy e SciPy. Baixe as últimas versões estáveis do NumPy e SciPy, e instale-as chamando pip install .whl a partir de um prompt de comando. Note que você deve baixar a versão correspondente ao seu ambiente Python (2.7 neste caso) e o tamanho das palavras. Por exemplo, em sistemas/intérpretes de 32 bits:

pip install numpy-1.9.2+mkl-cp27-none-win32.whlpip install scipy-0.15.1-cp27-none-win32.whl

E para sistemas/intérpretes de 64 bits:

pip install numpy-1.9.2+mkl-cp27-none-win_amd64.whlpip install scipy-0.15.1-cp27-none-win_amd64.whl

Após a instalação, você deve ser capaz de executar import numpy e import scipy a partir de um interpretador Python para verificar se os módulos foram instalados corretamente. Você pode verificar quais versões do NumPy e SciPy estão instaladas de numpy.__version__ e scipy.__version__, respectivamente.

Instalando o módulo Python-OpenCV

Por último, precisamos copiar o módulo OpenCV para os pacotes Python locais. Nos arquivos extraídos de opencv-3.0.0-rc1.exe, vá para a pasta opencv\build\python.7\, e abra a pasta x86\ (para 32 bits) ou x64\ (para 64 bits). Em cada um, haverá um arquivo cv2.pyd.

Copiar cv2.pyd diretamente no diretório Lib\site-packages\ da sua instalação Python. Para a maioria dos usuários, isto será encontrado em:

C:\Python27\Lib\site-packages 

Por último, certifique-se de que os arquivos .dll do OpenCV estão em algum lugar no arquivo %PATH% do seu sistema, especialmente o arquivo opencv_ffmpeg310.dll (ou opencv_ffmpeg310_64.dll para sistemas de 64 bits) necessário para carregar arquivos de vídeo.

Continue para a seção Verificar Instalação para garantir que tudo foi instalado corretamente, e a nova versão do OpenCV está sendo usada. Certifique-se também de verificar a próxima página, Migração & Alterações, para detalhes sobre as alterações no módulo e atualização do código existente.

Instalando no Linux (compilando do código fonte)

Embora este guia seja escrito para Ubuntu 12.04/14.04 e outras variantes (por exemplo Xubuntu/Lubuntu/Kubuntu), o processo deve ser em grande parte o mesmo em outras versões, assim como em distribuições Linux similares ao Debian. Preste atenção na saída de cada comando para garantir que tudo funcionou corretamente, e se houver algum problema durante o processo de construção, veja o final deste documento para possíveis mitigações

Downloading OpenCV

Para começar, baixe o OpenCV para Linux (versão 3.1.0, opencv-3.1.0.zip), e extraia-o para um diretório de sua escolha (por exemplo ~/opencv-src). Crie uma pasta build dentro da pasta onde o arquivo foi extraído (o diretório contendo o arquivo CMakeLists.txt), e abra uma sessão terminal lá. Por exemplo:

# Assuming the files were extracted to ~/opencv-src/...cd ~/opencv-srcmkdir buildcd build

Executar todos os comandos seguintes da própria subpasta build, assim os arquivos compilados serão colocados lá.

Installing Build Dependencies

Para compilar o OpenCV, devemos assegurar que as dependências requeridas estejam disponíveis, incluindo as próprias ferramentas de compilação. Podemos obter as requeridas usando apt no Ubuntu, mas primeiro, assegure-se que a lista de pacotes está atualizada executando apt-get update. Em seguida, execute os seguintes comandos para obter os pacotes necessários (veja abaixo para uma lista de uma linha de todos):

sudo apt-get install cmake build-essential pkg-configsudo apt-get install libgtk2.0-dev libtbb-devsudo apt-get install python-dev python-numpy python-scipysudo apt-get install libjasper-dev libjpeg-dev libpng-dev libtiff-dev sudo apt-get install libavcodec-dev libavutil-dev libavformat-dev libswscale-devsudo apt-get install libdc1394-22-dev libv4l-dev

Em uma linha:

sudo apt-get install cmake build-essential pkg-config libgtk2.0-dev libtbb-dev python-dev python-numpy python-scipy libjasper-dev libjpeg-dev libpng-dev libtiff-dev libavcodec-dev libavutil-dev libavformat-dev libswscale-dev libdc1394-22-dev libv4l-dev

Note que para módulos/características adicionais do OpenCV (por exemplo, suporte a GPU/CUDA, ou módulo Python 3), você precisará baixar os respectivos pacotes de desenvolvimento/SDK para essas bibliotecas também. As dependências listadas acima cobrem apenas a construção do OpenCV em si e do Python 2.7 cv2 module.

Compilar e instalar o OpenCV

Agora temos as dependências de construção necessárias, execute cmake (novamente, no diretório build/ que criamos) para gerar o Makefile para construir o OpenCV:

cmake -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=/usr/local ..

Se houver algum erro, certifique-se de que você baixou todos os pacotes necessários – a saída deve ajudar a rastrear o que está faltando. Para garantir que o módulo Python será compilado, você deve ver python2 na lista de módulos configurados após executar cmake:

-- Linker flags (Release):-- Linker flags (Debug):-- Precompiled headers: YES---- OpenCV modules:-- To be built: hal core flann imgproc ml python2

Se você não vir o módulo python2 listado, na lista “To be built”, verifique se você tem os pacotes de desenvolvimento Python apropriados instalados, remova todos os arquivos da pasta build/, e tente executar o comando cmake novamente.

Agora, podemos compilar o OpenCV (e o módulo Python) usando make, e instalá-lo em nosso sistema:

makesudo make install

Certifique-se de que a compilação foi bem sucedida após chamar make, e verifique a saída antes de instalar. Se você se deparar com problemas/erros de compilação, mais uma vez assegure-se de que você tem todas as dependências e arquivos de cabeçalho necessários no seu sistema. Se existem problemas de compilação reais com o próprio OpenCV, veja a seção Problemas de compilação do Linux abaixo para algumas possíveis soluções.

Quando instalei o OpenCV 3.0-rc1 no Ubuntu 12.04, encontrei erros de compilação em relação a alguns codecs ausentes #define entradas. Como mencionado, os passos para fazer isso são detalhados abaixo caso você encontre o mesmo problema (o problema deve ser resolvido na versão 3.1.0 e acima). O Ubuntu 14.04 e superior deve compilar com sucesso sem requerer quaisquer modificações.

Se a compilação foi bem sucedida, mas você não pode import cv2 a partir de uma shell Python após executar make install, você pode instalar o módulo manualmente copiando o ficheiro cv2.so que acabámos de compilar na pasta build/lib/ para /usr/local/lib/python2.7/dist-packages/. A partir da pasta build/, isto pode ser feito por:

sudo cp lib/cv2.so /usr/local/lib/python2.7/dist-packages/

Após este passo, o módulo cv2 é instalado, e agora pode ser importado pelo seu ambiente Python. Continue para a seção Verificando Instalação para assegurar que tudo foi instalado corretamente, e mais importante, que a versão correta do OpenCV está sendo usada pelo Python. Você também pode verificar na próxima página, Migração & Alterações, para detalhes sobre as alterações no módulo cv2, e que alterações precisam ser feitas no código existente para rodar com o módulo atualizado.

Verificando Instalação

Como mencionado anteriormente, você pode verificar se o módulo cv2 foi instalado corretamente executando o seguinte em uma shell Python:

import cv2print cv2.__version__

Se a string da versão correta for impressa (3.0.0-rc1 ou mais recente se você usou uma versão mais recente), tudo é instalado corretamente neste ponto!

Note que existem algumas grandes alterações na própria hierarquia de módulos cv2, e programas Python escritos com o OpenCV 2.4.x em mente podem não funcionar mais corretamente. Veja a próxima seção, Migração & Alterações para detalhes sobre as alterações, e como modificar programas para lidar com as alterações.

Problemas de compilação do Linux

Em alguns sistemas você pode ter problemas ao compilar o próprio OpenCV, dependendo de quais pacotes estão disponíveis. Se os arquivos de cabeçalho apropriados estão disponíveis, mas ainda assim surgem problemas de compilação, tente ver se há alguma solução abaixo para o problema.

Undefined AV_CODEC_ID_... in ffmpeg_codecs.hpp

Se você se deparar com um problema onde os erros de compilação são causados por certos codecs não definidos, você pode baixar uma versão mais recente de ffmpeg_codecs.hpp daqui, e substituí-la no código fonte que você baixou/extraído na pasta modules/videoio/src/.

Alternativamente, você pode declará-los manualmente editando o arquivo ffmpeg_codecs.hpp, adicionando a entrada do codec que falta para H263I, e renomeando WNV para WNV1. Você pode ver que alterações devem ser feitas vendo esta submissão do projeto GitHub do OpenCV.

Após o arquivo ser atualizado, você pode chamar make novamente da pasta build/, e o OpenCV deve terminar a compilação sem erros agora.