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>请参考：包括零个或多个