OpenCV二次开发 编程规范



遵循规范编程是程序员的良好习惯。OpenCV编程规范对命名、文件结构、函数及实现、代码布局、可移植性、文件操作、文档编写等进行了规范。遵守并熟悉这些规范，有利于更好的学习了解OpenCV，写出可读性的代码。

1.文件命名规则

所有的Cv和CvAux库文件的命名必须符合以下规则。

1)前缀位cv;

2)C/C++头文件扩展名为”.h”，C++头文件扩展名为”.hpp”;

3)源文件扩展名”.cpp”；

4)文件名小写，兼容POSIX；

 

2.数据类型和函数的命名规则

函数和数据结构使用大小写混合样式：

1）外部函数使用前缀cv。

2）内部函数使用前缀icv。

3）数据结构（C结构体，枚举，联合体，类）使用前缀Cv。

宏名称全部使用大写字符，词间下划线分割，外部宏使用前缀CV_,内部宏使用前缀ICV_。

 

3.文件结构

1>源文件以BSD兼容的许可声明开头。

//M*//////////////////////////////////////////////////////////////////////////////////////

//

//  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.

//

//  By downloading, copying, installing or using the software you agree to this license.

//  If you do not agree to this license, do not download, install,

//  copy or use the software.

//

//

//                        Intel License Agreement

//                For Open Source Computer Vision Library

//

// Copyright (C) 2000, Intel Corporation, all rights reserved.

// Third party copyrights are property of their respective owners.

//

// Redistribution and use in source and binary forms, with or without modification,

// are permitted provided that the following conditions are met:

//

//   * Redistribution's of source code must retain the above copyright notice,

//     this list of conditions and the following disclaimer.

//

//   * Redistribution's in binary form must reproduce the above copyright notice,

//     this list of conditions and the following disclaimer in the documentation

//     and/or other materials provided with the distribution.

//

//   * The name of Intel Corporation may not be used to endorse or promote products

//     derived from this software without specific prior written permission.

//

// This software is provided by the copyright holders and contributors "as is" and

// any express or implied warranties, including, but not limited to, the implied

// warranties of merchantability and fitness for a particular purpose are disclaimed.

// In no event shall the Intel Corporation or contributors be liable for any direct,

// indirect, incidental, special, exemplary, or consequential damages

// (including, but not limited to, procurement of substitute goods or services;

// loss of use, data, or profits; or business interruption) however caused

// and on any theory of liability, whether in contract, strict liability,

// or tort (including negligence or otherwise) arising in any way out of

// the use of this software, even if advised of the possibility of such damage.

//

//M*/

2>每行最多90字符（粗略），不包括行结束符。

3>不是制表符，使用4空格缩进。

4>头文件必须使用保护宏。

5>混合C/C++ 接口文件使用 extern ”C”{}

6>VC++下编译，源文件必须包含预编译头precomp.h。

 

4.函数接口设计

为了保持库的一致性，应根据以下方式设计接口：

1>函数功能：定义良好，精简

2>函数名称：简单，体现函数功能。一般形式为cv+ActionName+Object+modeifiers

对容器元操作时，函数名为 ContainerName+ActionName

3>函数返回值：以简化功能为目的。不能使用会导致严重错误的类型（空指针、0除数、错误参数类型、不支持的图像格式等）作为返回值

4>参数类型：尽量使用Opencv中的常用数据结构类型：光栅图像IplImage（CV 1.X），矩阵CvMat（常用于图像矩阵 CV2.X~）、轮廓线CvSeq等。不建议使用简单指针等。

5>参数顺序：输入参数、输出参数、标记或可选参数。输入参数一般用const修饰。对于矩阵操作或类局域函数（一般为内部函数）顺序为：容器（指针），元素信息（位置）、标记或可选参数。可选参数或标记根据重要性依次排列，一般可赋初值。

6>参数默认值：简化函数用法。C++编程环境中函数的参数可赋予默认值。在函数声明中，使用宏CV_DEFAULT指定参数的默认值，与C语言编程环境相兼容。

可参考CV_DEFAULT宏定义

#ifndef CV_DEFAULT

#  ifdef __cplusplus

#    define CV_DEFAULT(val) = val

#  else

#    define CV_DEFAULT(val)

#  endif #endif

 

 

5.函数实现

主要对参数类型检测、错误产生和处理、内存管理和资源回收、调用低级函数做出了规定：

1>参数类型检测：OpenCV广泛使用高级数据类型传送和返回参数。简化了函数使用，却增加了错误参数调用函数的可能性。因此在使用输入参数和返回参数时应该检查参数类型是否正确。例如IplImage通过宏CV_CHECK_IMAGE被检查。CV_CHECK_MASK_IAMGE可检查掩码图像。

2>错误产生和处理：任何时候，当传入一个错误的参数或在函数执行时发生其他严重错误时，应该通过cvError函数抛出一个错误信号。Opencv的错误机制是用一个全局错误状态代替返回错误码，实现方法是使用cvError函数设置、用cvClearErrStatus清除、用cvGetErrorStatus读取。除了设置错误状态和指定值外，cvError还能进行其他操作，依据错误处理的模式的不同而不同，错误处理模式可以通过cvSetErrorMode调整。在Silent模式或parent模式下，cvError以及返回；在子模式下，它打印错误消息并终止应用程序。为了更方便的使用，可以通过使用宏来代替以上函数，如CV_ERROR和OPENCV_ERROR。用CV_CALL和OPENCV_CALL来代替函数和检查状态。

3>内存管理和资源回收：在opencv中临时缓存用cvAlloc和cvFree函数分配和回收。函数应该注意适当对齐，对未释放的内存保存跟踪并检查溢出。临时图像、内存存储和其他结构使用cvCreate<object>和cvRelease<object>的方式来分配和回收。如果错误发生，并且CV_ERROR或CV_CALL宏被调用，那么控制转到exit标签处，同时在程序流中可以通过EXIT宏跳转控制。标签可以通过手动或通过_BEGIN_宏来定义，引入此标签是为了资源回收。程序执行时可能经常会发生内存溢出的情况。使用OpenCV库中的一些技术方法，可以帮助程序员避免大多数内存溢出错误。例如，在函数开始清除所有指针，在“exit”标签后对每一个指针调用cvFree函数，在函数内部返回语句用EXIT宏代替，这样可以确保内存回收。

4>调用低级函数：OpenCV中的低级函数主要是用C语言实现的原始操作。它们主要使用简单指针和基本数值类型，几乎不使用结构体，也不同于前面谈论的错误处理方法，错误返回代码而不是全局错误状态。调用这些函数的安全方法是使用宏IPPI_CALL。

6.代码布局

每个文件必须使用一致的格式。

修改别人的代码，应与原代码格式一致。

7.可移植性

为了满足可移植性：

1>ANSI C 第一个语言标准ISO/IEC 9899-1990.

2>C9X（1999年修订的新标准）：ISO/IEC 9899

3>C++标准：ISO/IEC 14882-1998.

去掉依赖编译器或者平台和系统调用的一些写法：

1>编译器：pragma’s

2>特定关键字：_stdcall、_inline 和_int64，应分别使用CV_INLINE、CV_STDCALL和int64代替。

3>编译器扩展

4>内联汇编

5>Unix或Win32调用

6>用sizeof代替具体的数据大小，用简单的字符处理数据，使用短形式或使用预处理指令包含非可移植性代码片段。

8.文档编写

文档以HTML格式提供。每个函数的文档或相关函数组的文档放入不同文件中，该文件可以通过主页连接访问。函数文档的HTML文档顺序包含以下基本元素。

1>页面标题：显示在浏览器标题栏中，表示一个扩展的函数名或一组函数名

2>关键字列表:用于搜索引擎和各种工具检索文档

3>可见的页面标题：重复页面标题

4>函数名：真实函数名，作为标签

5>简介：单行函数描述、

6>函数声明：按其在头文件中的形式，用<pre></pre>包含，

7>函数参数描述：用格式<参数名，描述>表示的列表。

8>讨论：描述函数功能、允许或支持的参数组合的限制、算法参考

9>使用实例：可选的代码片段或伪代码，几个相关的函数可以一并参考一个实例。

10>请参考：包括零个或多个