Инициализация

Материал из CompVision

CreateImage

Создает заголовок и выделяет память под данные изображения.

IplImage* cvCreateImage( CvSize size, int depth, int channels );

size - задает ширину и высоту изображения.

depth - задает битовую глубину элементов изображения. Может принимать значения:

   * IPL_DEPTH_8U - беззнаковые 8-битные целые (байт)
   * IPL_DEPTH_8S - 8 битные целые со знаком
   * IPL_DEPTH_16U - беззнаковые 16 - битные целые
   * IPL_DEPTH_16S - 16- битные целые со знаком
   * IPL_DEPTH_32S - 32 - битные целые со знаком
   * IPL_DEPTH_32F - плавающая точка одинарной точности
   * IPL_DEPTH_64F - плавающая точка двойной точности

channels - количество каналов на элемент (пиксел). Может быть 1,2,3 или 4. Каналы чередуются, например, обычное расположение цветовых данных в изображении такое - b0 g0 r0 b1 g1 r1 ... , где b0, g0, r0 - значение для компоненты цвета нулевого пикселя, b1, g1, r1 - значение для компоненты цвета первого пикселя.

Формат изображения IPL может хранить и нечередующиеся цветовые данные, сначала все синие, потом красные, потом зеленые компоненты. И некоторые функции OpenCV могут с ними работать. Однако Createimage создает только изображения с чередующимися цветовыми данными. Функция вызывает:

функцию создания заголовка

header = cvCreateImageHeader(size,depth,channels);

и функцию выделения памяти для данных изображения.

cvCreateData(header);

CreateImageHeader - Выделяет память, инициализирует структуру IplImage (память под данные изображения не выделяются)

IplImage* cvCreateImageHeader( CvSize size, int depth, int channels );

size - задает ширину и высоту изображения.

depth - задает битовую глубину элементов изображения. Может принимать значения:

   * IPL_DEPTH_8U - беззнаковые 8-битные целые (байт)
   * IPL_DEPTH_8S - 8 битные целые со знаком
   * IPL_DEPTH_16U - беззнаковые 16 - битные целые
   * IPL_DEPTH_16S - 16- битные целые со знаком
   * IPL_DEPTH_32S - 32 - битные целые со знаком
   * IPL_DEPTH_32F - плавающая точка одинарной точности
   * IPL_DEPTH_64F - плавающая точка двойной точности

channels - количество каналов на элемент (пиксел). Может быть 1,2,3 или 4. Каналы чередуются, например, обычное расположение цветовых данных в изображении такое - b0 g0 r0 b1 g1 r1 ... , где b0, g0, r0 - значение для компоненты цвета нулевого пикселя, b1, g1, r1 - значение для компоненты цвета первого пикселя.

Формат изображения IPL может хранить и нечередующиеся цветовые данные, сначала все синие, потом красные, потом зеленые компоненты. И некоторые функции OpenCV могут с ними работать. Однако Createimage создает только изображения с чередующимися цветовыми данными. Эта функция является аналогом функции IPL:

iplCreateImageHeader( channels,
0,
depth,
channels == 1 ? "GRAY" : "RGB",
channels == 1 ? "GRAY" : channels == 3 ? "BGR" : channels == 4 ? "BGRA" : "",
IPL_DATA_ORDER_PIXEL,
IPL_ORIGIN_TL,
4,
size.width,
size.height,
0,0,0,0);

Однако она не использует функции IPL по умолчанию, см. макрос CV_TURN_ON_IPL_COMPATIBILITY.

ReleaseImage

Освобождает память, выделенную под изображение

Освобождает память, занимаемую данными заголовка и изображения.

void cvReleaseImage( IplImage** image );

image - двойной указатель на заголовок освобождаемого изображения.

ReleaseImage вызывает две функции:

if( *image )
{
cvReleaseData( *image );
cvReleaseImageHeader( image );
}

InitImageHeader

Инициализирует выделенный пользователем заголовок

IplImage* cvInitImageHeader( IplImage* image, CvSize size, int depth, int channels, int origin=0, int align=4 );

size - задает ширину и высоту изображения.

depth - задает битовую глубину элементов изображения. Может принимать значения:

   * IPL_DEPTH_8U - беззнаковые 8-битные целые (байт)
   * IPL_DEPTH_8S - 8 битные целые со знаком
   * IPL_DEPTH_16U - беззнаковые 16 - битные целые
   * IPL_DEPTH_16S - 16- битные целые со знаком
   * IPL_DEPTH_32S - 32 - битные целые со знаком
   * IPL_DEPTH_32F - плавающая точка одинарной точности
   * IPL_DEPTH_64F - плавающая точка двойной точности

channels - количество каналов на элемент (пиксел). Может быть 1,2,3 или 4. Каналы чередуются, например, обычное расположение цветовых данных в изображении такое - b0 g0 r0 b1 g1 r1 ... , где b0, g0, r0 - значение для компоненты цвета нулевого пикселя, b1, g1, r1 - значение для компоненты цвета первого пикселя.

origin - начало отсчета может быть IPL_ORIGIN_TL или IPL_ORIGIN_BL.

align - выравнивание для строк изображения, обычно 4 или 8 байт. Функция возвращает указатель на инициализированный заголовок.

CloneImage

Создает полную копию изображения, включая заголовок ROI и данные

IplImage* cvCloneImage( const IplImage* image );

image - клонируемое изображение

SetImageCOI

Устанавливает канал интереса (проще говоря, цветовой слой)

void cvSetImageCOI( IplImage* image, int coi );

image - входное изображение,

coi - номер канала.

coi = 0 - выбраны все каналы, coi = 1 выбран первый канал, и т.д. Если ROI равен NULL и coi не равен 0 выделяется ROI.

Замечание: Большинство функций OpenCV не поддерживают работу с COI, таким образом, чтобы работать с отдельными слоями изображений или матриц, рекомендуется использовать функции cvSplit для разложения на слои и cvPlaneToPix для сборки многослойного изображения.

GetImageCOI

Возвращает канал интереса (проще говоря, цветовой слой)

image - входное изображение возвращает канал интереса если возвращает 0 значит COI не назначен.

SetImageROI

Устанавливает область интереса на изображении

void cvSetImageROI( IplImage* image, CvRect rect );

image - входное изображение

rect - прямоугольник области интереса

Если ROI изображения равно NULL, а rect не равно прямоугольнику, равному всему изображению, создается ROI. В отличие от COI с ROI работает большинство функций OpenCV. В случае выделения на изображении области интереса, функции работающие с этим изображением видят лишь область интереса, и обрабатывают ее так, как если бы это было отдельное изображение. Координаты пикселей тоже отсчитываются как на нормальном изображении с началом координат в начале координат ROI.

ResetImageROI

Отменяет (освобождает память) ROI изображения

Отменяет (освобождает память) ROI изображения, после этого все изображение обабатывается функциями библиотеки.

Аналогичный результат может быть получен вызовом функций:

cvSetImageROI( image, cvRect( 0, 0, image->width, image->height ));
cvSetImageCOI( image, 0 );

Но последний вариант не освобождает image->roi.

GetImageROI

Возвращает координаты области интереса

CvRect cvGetImageROI( const IplImage* image );

image - входное изображение структура cvRect (0,0, image->width,image->height) возвращается когда ROI для данного изображения не задана.

CreateMat

Создает новую матрицу

CvMat* cvCreateMat( int rows, int cols, int type );

rows - количество строк в матрице

cols - количество столбцов в матрице

type - тип элементов матрицы обычно задаваемый в форме CV<глубина в битах>(S или U или F)C<количество каналов>, например: CV_8UC1 означает что матрица состоит из одного канала 8 битных беззнаковых целых элементов, а CV_32SC2 означает что в матрице 2 канала 32 битных значений со знаком. Функция выделяет память для заголовка матрицы и для данных, которые там будут содержаться. Аналогичные действия можно сделать вызвав функции:

CvMat* mat = cvCreateMatHeader( rows, cols, type );
cvCreateData( mat );

Элементы матрицы хранятся в памяти строка за строкой, все строки выровнены по 4 байтам.

CreateMatHeader

Создает заголовок матрицы

CvMat* cvCreateMatHeader( int rows, int cols, int type );

rows - количество строк в матрице

cols - количество столбцов в матрице

type - тип элементов матрицы обычно задаваемый в форме CV<глубина в битах>(S или U или F)C<количество каналов>, например: CV_8UC1 означает что матрица состоит из одного канала 8 битных беззнаковых целых элементов, а CV_32SC2 означает что в матрице 2 канала 32 битных значений со знаком. Выделяет память только для заголовка матрицы, но не для данных. Память для данных может быть выделена в дальнейшем при помощи функций: cvCreateData или может быть установлен указатель на уже существующий массив данных, при помощи функции cvSetData.

ReleaseMat

Освобождает память, занятую матрицей (данными и заголовком)

void cvReleaseMat( CvMat** mat );

mat - двойной указатель на матрицу.

Аналогичные действия могут быть выполнены командами:

if( *mat ) cvDecRefData( *mat );
cvFree( (void**)mat );

InitMatHeader

Инициализирует заголовок матрицы

CvMat* cvInitMatHeader( CvMat* mat, int rows, int cols, int type, void* data=NULL, int step=CV_AUTOSTEP );

mat - указатель на заголовок матрицы, который мы хотим инициализировать

rows - количество строк в матрице

cols - количество столбцов в матрице

type - тип элементов матрицы обычно задаваемый в форме CV<глубина в битах>(S или U или F)C<количество каналов>, например: CV_8UC1 означает что матрица состоит из одного канала 8 битных беззнаковых целых элементов, а CV_32SC2 означает что в матрице 2 канала 32 битных значений со знаком.

data - необязательный параметр, указывающий на данные. Назначается полная ширина строки в байтах. По умолчанию используется минимальный возможный шаг, то есть последовательные строки размещаются в памяти без проммежутков, одна за другой.

Функция InitMatHeader инициализирует только заголовок, под который уже выделена память.

Ниже приводится пример расчета матричного произведения.

//--------------------------------------------------------
double a[] = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 };
double b[] = { 1, 5, 9, 2, 6, 10, 3, 7, 11, 4, 8, 12 };
 
double c[9];
CvMat Ma, Mb, Mc ;
 
cvInitMatHeader( &Ma, 3, 4, CV_64FC1, a );
cvInitMatHeader( &Mb, 4, 3, CV_64FC1, b );
cvInitMatHeader( &Mc, 3, 3, CV_64FC1, c );
 
cvMatMulAdd( &Ma, &Mb, 0, &Mc );
// массив c содержит произведение матриц a(3x4) и b(4x3)
//--------------------------------------------------------

Mat

Инициализирует заголовок матрицы (облегченный вариант)

CvMat cvMat( int rows, int cols, int type, void* data=NULL );

rows - количество строк в матрице

cols - количество столбцов в матрице

type - тип элементов матрицы обычно задаваемый в форме CV<глубина в битах>(S или U или F)C<количество каналов>, например: CV_8UC1 означает что матрица состоит из одного канала 8 битных беззнаковых целых элементов, а CV_32SC2 означает что в матрице 2 канала 32 битных значений со знаком.

data - необязательный параметр, указывающий на данные.

Размещает данные на которые указывает data строка за строкой.

Функция при компиляции заменяется inline подстановкой строк:

CvMat mat;
cvInitMatHeader( &mat, rows, cols, type, data, CV_AUTOSTEP );

CloneMat

Создает копию матрицы

CvMat* cvCloneMat( const CvMat* mat );

mat - входная матрица

Функция создает полную копию матрицы и возвращает на неё указатель.

CreateMatND

Cоздает многомерную плотную матрицу

CvMatND* cvCreateMatND( int dims, const int* sizes, int type );

dims - количество измерений массива должен быть меньше чем CV_MAX_DIM по умолчанию CV_MAX_DIM=32.

sizes - массив размеров измерений

type - тип элементов матрицы обычно задаваемый в форме CV<глубина в битах>(S или U или F)C<количество каналов>, например: CV_8UC1 означает что матрица состоит из одного канала 8 битных беззнаковых целых элементов, а CV_32SC2 означает что в матрице 2 канала 32 битных значений со знаком.

Функция CreateMatND выделяет память под заголовок многомерного плотного массива и его данных, после чего возвращает указатель на созданный массив. Те же действия можно выполнить вызвав функции:

CvMatND* mat = cvCreateMatNDHeader( dims, sizes, type );
cvCreateData( mat );

CreateMatNDHeader

Создает новый заголовок матрицы

CvMatND* cvCreateMatNDHeader( int dims, const int* sizes, int type );

dims - количество измерений матрицы

sizes - массив размеров измерений

type - тип элементов матрицы обычно задаваемый в форме CV<глубина в битах>(S или U или F)C<количество каналов>, например: CV_8UC1 означает что матрица состоит из одного канала 8 битных беззнаковых целых элементов, а CV_32SC2 означает что в матрице 2 канала 32 битных значений со знаком. Функция CreateMatNDHeader выделяет память под заголовок многомерной плотной матрицы. Память для данных может быть выделена позднее, при помощи функций cvCreateData или может быть установлен указатель на уже существующий массив данных, при помощи функции cvSetData.

ReleaseMatND

Освобождает память из под многомерной матрицы

void cvReleaseMatND( CvMatND** mat );

mat - двойной указатель на освобождаемую матрицу.

Аналогичный результат достигается вызовом функций:

if( *mat )
cvDecRefData( *mat );
cvFree( (void**)mat );

InitMatNDHeader

Инициализирует заголовок многомерной матрицы

CvMatND* cvInitMatNDHeader( CvMatND* mat, int dims, const int* sizes, int type, void* data=NULL );

mat - указатель на инициализируемый заголовок.

dims - количество измерений матрицы

sizes - массив размеров измерений

type - тип элементов матрицы обычно задаваемый в форме CV<глубина в битах>(S или U или F)C<количество каналов>, например: CV_8UC1 означает что матрица состоит из одного канала 8 битных беззнаковых целых элементов, а CV_32SC2 означает что в матрице 2 канала 32 битных значений со знаком. Функция InitMatNDHeader инициализирует структуру типа CvMatND под которую пользователем была выделена память.

CloneMatND

Создает полную копию многомерной матрицы

CvMatND* cvCloneMatND( const CvMatND* mat );

mat - копируемая матрица.

Функция CloneMatND - создает полную копию многомерной матрицы и возвращает указатель на неё.

DecRefData

Уменьшает на единицу счетчик ссылок на область памяти с данными

void cvDecRefData( CvArr* arr );

arr - заголовок матрицы

функция cvDecRefData уменьшает счетчик ссылок на данные структур CvMat и CvMatND если он не NULL и освобождает память занимаемую данными, если счетчик достигает значения 0. В текущей реализации счетчик ссылок на данные не равен NULL только если память под данные была выделена при помощи функции cvCreateData, во всех других случаях, таких как:

указатель назначен на внешние данные;

заголовок матрицы представляет собой часть бОльшей матрицы или изображения;

заголовок матрицы был сконвертирован из изображения или заголовка N-мерной матрицы,

счетчик ссылок на данные равен NULL и, следовательно, не уменьшается.

Всякий раз, освобождались данные или нет, указатель на данные и счетчики ссылок очищаются функцией.

IncRefData

Увеличивает на единицу счетчик ссылок на область памяти с данными

arr - заголовок матрицы функция cvIncRefData увеличивает счетчик ссылок на данные структур CvMat и CvMatND и возвращает его значение если он не NULL иначе возвращает 0.

CreateData

Выделяет в памяти место под данные матрицы

void cvCreateData( CvArr* arr );

arr - заголовок матрицы

функция cvCreateData выделяет память под данные изображения, матрицы или многомерной матрицы. Эта функция выделения памяти используется OpenCV в том случае, если выключена опция CV_TURN_ON_IPL_COMPATIBILITY, иначе используются функции из библиотеки IPL.

ReleaseData

Освобождает память занятую данными матрицы

void cvReleaseData( CvArr* arr );

arr - заголовок матрицы.

Функция cvReleaseData - освобождает память занятую данными матрицы в случае CvMat и CvMatND она просто вызывает cvDecRefData(), т.к. не может освободить память, выделенную отдельно, на которую просто потом был установлен указатель. Смотрите также замечания по cvCreateData.

SetData

Назначает указатель на данные заголовку матрицы

void cvSetData( CvArr* arr, void* data, int step );

arr - заголовок матрицы

data - указатель на данные

step - полная длина строки в байтах

Функция cvSetData назначает указатель на данные заголовку матрицы. Заголовок должен быть инициализирован перед использованием. Для этого можно применить функции:

cvCreate*Header, cvInit*Header или cvMat (в случае матрицы).

(* = Mat, MatND, и т.д.)

GetRawData

Возвращает низкоуровневую информацию о матрице

void cvGetRawData( const CvArr* arr, uchar** data, int* step=NULL, CvSize* roi_size=NULL );

arr - заголовок матрицы

data - (выходное значение) указатель на начало области памяти изображения (данных матрицы), или, если задана ROI, то на начало памяти ROI.

step - (выходное значение) полная длина строки в байтах.

roi_size - (выходное значение) размеры ROI (ширина и высота). Функция cvGetRawData заполняет выходные переменные информацией о данных изображения (матрицы). Все возвращаемые параметры необязательные и могут иметь значение NULL, если в них нет необходимости.

Пример показывает, как получить доступ к элементам матрицы, используя эту функцию.

Функция преобразует элементы матрицы в положительные (вычисляет абсолютные значения)

float* data;
int step;
 
CvSize size;
int x, y;
 
cvGetRawData( array, (uchar**)&data, &step, &size );
step /= sizeof(data[0]);
 
for( y = 0; y < size.height; y++, data += step )
for( x = 0; x < size.width; x++ )
    data[x] = (float)fabs(data[x]);

GetMat

Возвращает заголовок произвольной матрицы (прим. служит для преобразования IplImage или CvMatND в CvMat.)

CvMat* cvGetMat( const CvArr* arr, CvMat* header, int* coi=NULL, int allowND=0 );

arr - входная матрица.

header - указатель на структуру CvMat, используемую как временный буфер.

coi - необязательный выходной параметр для хранения канала интереса (COI).

AllowND - если не нуль функция принимает многомерные плотные матрицы (CvMatND*) и возвращает двумерные (если CvMAtND имеет два измерения) или одномерные (когда CvMatND имеет одно измерение или больше двух измерений). Матрица должна быть непрерывной.

Функция cvGetMat возвращает заголовок входной матрицы, которая может быть матрицей - CvMat, изображением IplImage или многомерным плотным массивом CvMatND* (если allowND!=0). В случае матрицы, функция просто возвращает на неё указатель (тот-же что передаем в параметрах), В случае изображения или CvMatND* она инициализирует структуру header параметрами текущей области интереса (ROI) и возвращает указатель на эту временную структуру. Так как канал интереса (COI) не поддерживается CvMat он возвращается отдельным параметром.

Функция обеспечивает простой путь управления обоими типами матриц - IplImage и CvMat путем использования одного и того же кода. Обратное преобразование из CvMat в IplImage осуществляется при помощи функции cvGetImage.

Входная матрица должна иметь выделенную область памяти для данных, то есть указатель на данные не должен быть NULL. Если входная матрица является IplImage с плоским расположением данных и установлен канал интереса (COI), функция возвращает указатель на текущую плоскость изображения и COI=0. Это позволяет обрабатывать многоканальные изображения с планарным расположением данных по плоскостям (каналам).

GetImage

Преобразует матрицу в изображение

arr - входная матрица

image_header - указатель на структуру IplImage, используемую как временный буфер.

Функция cvGetImage - возвращает заголовок изображения, для входной матрицы, которая может быть CvMat*, или изображением - IplImage*. В случае изображения, функция просто возвращает на него указатель. В случае CvMat* она инициализирует структуру image_header прамаметрами фходной матрицы.

Заметте, если мы преобразуем IplImage в CvMat и потом проводим обратное преобразование, мы можем получить различные заголовки, если установлна область интереса (ROI), и тогда, некоторые функции, которые вычисляют шаг по ширине и выравниванию могут не работать.

CreateSparseMat

Создает разреженную матрицу

CvSparseMat* cvCreateSparseMat( int dims, const int* sizes, int type );

dims - количество измерений матрицы. В отличие оот плотной матрицы, количество измерений практически неограничено (2^16).

sizes - массив размеров измерений.

type - тип элеменотов матрицы (см. CvMat).

Функция выделяет место под многомерную разреженную матрицу. Изначально массив не содержит элементов, и функции cvGet*D и cvGetReal*D возвращают 0 для любых индексов.

ReleaseSparseMat

Освобождает память от разреженной матрицы

void cvReleaseSparseMat( CvSparseMat** mat );

mat - двойной указатель на матрицу Функция очищает разреженную матрицу, затем очищает указатель.

CloneSparseMat

Создает полную копию разреженной матрицы

mat - копируемая матрица

CloneSparseMat - создает полную копию разреженной матрицы и возвращает указатель на копию.