阳光人脸识别二次开发包说明书.docx
《阳光人脸识别二次开发包说明书.docx》由会员分享，可在线阅读，更多相关《阳光人脸识别二次开发包说明书.docx（42页珍藏版）》请在冰豆网上搜索。
阳光人脸识别二次开发包说明书
阳光人脸识别二次开发包（V3.51）说明书
注：
附件SDK_V2.7版，仅供用户学习本SDK的调用方法。
识别性能测试请使用最高版本的SDK。
第一部分产品的性能评估，应用说明，问题等。
第二部分主要是SDK函数的使用说明。
<<目录>>
第一部分
一．产品的版权
二．产品的版本
三．产品的重要特点
四．如何使用范例代码
五．如何采模板
六．如何设置相似度阀值
七．图像格式，大小，人脸大小怎样最佳
八．产品的适用人群
九．人脸特征数据的保存
十．如何鉴别两套人脸识别SDK的优劣
十一.在DELPHI下做二次开发的注意事项
十二.如何正确使用子功能
十三.SDK升级信息
十三.人脸检测性能指标
第二部分
一．输出数据-结构定义
二．SDK调用的-初始化部分
三．人脸识别主函数
四．赠送的USB视频函数
五．模板管理部分
六．输出调试变量
七．参数设置
八．活体识别
九．人工定位
十．背光模式下的人脸识别
十一.打瞌睡检测参考代码
十二.多线程范例
十三.人面搜索
附录：
（1）Ver2.7版的《人脸识别相似度阀值表》
（2）Ver3.51版的《人脸识别相似度阀值表》
第一部分
一．产品的版权
本品系国人完全自主知识产权开发，从底层开始即是自行编码，未引用任何第三方技术如（人脸识别库/图像识别算法库/开源代码）等资源。
更未引用其它公司的人脸识别SDK来做外壳调用型封装。
本品是VC开发，但只有极小部分用到了MFC函数,大部分CODE均为标准C++编写。
作者于2010年在北京申请了著作权，申请名称为：
人脸检测与识别算法软件
注：
国家软件版权申请现起禁止用SDK/开发包/系统/模块/库之类的字眼，一律用软件两字做结尾。
二．产品的版本
SunLightFace.exe是网站发布的演示程序，用户可以通过这个程序来测试SDK的性能。
SunLightFace.dll是SDK，其性能技术指标与演示程序是完全相同的。
目前这个版本全称是：
可见光主动识别版（非红外摄像头，配合识别）
另外还有两个版本：
可见光被动识别版，红外主动识别版。
（仅供定制用户）
用户可以用SunLightFace.dllVer2.7这个版本来做演练性的开发，从而掌握开发包的调用方法。
但识别能力的测试，应以当前发布的最高版本为准，Ver2.7版的识别能力较弱。
三．产品的重要特点
1.人脸检测的高正确率，误检，漏检很少，支持多脸（max=32）。
平面旋转高达60度，并带鼻，嘴定位，及眼镜判断等功能。
2.人脸识别的高精度，向用户推荐的识别阀值不仅能适应光线环境的变化，而且有高达97.18%以上的正确率。
带眼镜或头发挡住眉毛都行。
（但黑粗边眼镜的识别率相对低些，即在较好的识别环境下，黑粗边眼镜仍是OK的，只要看得清眼球，就对识别率没有任何影响）
3.在背光模式下（看上去黑黑的一大片），开启背光识别的开关后，识别速度会减低，把识别阀值调低一些，就仍然能进行准确的识别。
4.高精度的人眼定位，对高清大图，开启二次精定位开关后，能准确地定位人眼中的瞳孔。
准确的人眼定位，使用户能在此基础上开发出多款有创意的延伸产品。
四．如何使用范例代码
SunLightFace.dll是按WINDOWSAPI的标准调用来生成的动态库，并提供了VB,VC,C#三类范例代码，精简扼要，如果因VS版本问题无法打开，可以用其它文件编辑器打开.CPP,.H,.CS，.frm,.bas等文件来进行分析。
用户实际做应用项目时，可以直接粘贴范例代码到自己的工程中运行，只是注意调节好适当的参数值即可。
注意：
要把识别能力调好，照搬范例代码是不够的，需要仔细阅读本文档，做一些参数的设置和调节。
五．如何采模板
1.因为是主动配合识别，最好是采5张模板（总量是10张），正面1张，侧面2张，上仰下俯各1张，偏角不宜大（2-3度即可->微偏：
因为你在主动配合识别时不会故意地去偏着头识别，而是正对识别，但可能无心偏了一点，这里要求你“微偏”的目的就是为了和你将来可能的“无心偏了一点“对应），并都眼看着画面中的自己，因为眼球是定准比对的重要依据，所以无论是采模板还是识别，都眼看着画面中的自己最佳。
2.另外余下的5个模板，可以空，用于以后进行动态模板更新（后面第二部分详解），以适应人脸的长期发展变化。
当然，如果要求更稳定的识别效果，并有充分的时间和配合度，也可在每个方向上采上两个角度差不大的模板，这样总共就用掉9个模板，为了更好适应光线，还可再采不同光线的两套模板，这样就用掉18或27个模板。
个人模板的总量是可设置的，请参看后面的设置函数。
注意：
如果采的某几张模板在角度或光线上完全一样，这是没有任何意义的，等于只采了一张。
3.采模板时，光线不宜偏亮，也不宜偏暗，适中，并充分地反映出人脸轮廓。
这样的标准化模板才能更有效地去兼容那些人脸偏亮或偏暗的识别时段。
要让识别更准确，眼球附近就必须最大可能地清晰鲜明，同时眼球上最好不要反白光。
4.由于各个摄像头的焦距不同，可能对人脸轮廓的拉伸度也不同，所以，为达到最好的识别率，建议采集与识别完全用一模一样的摄像头。
5.及时画出采集的人脸模板照片，如果发现其中人眼定位不准确的，建议删除该模板重采，因为这样的模板是对识别无效的。
6.也有的公司拿去只采了一个正面的模板就开始用，但前提是光线环境好，被识别者自愿配合度高，打开了动态模板更新开关。
注意：
为了能长期地进行好1C1,1CN,请务必打开动态模板更新的开关，以保证库中的模板能随时间的推移与人脸同步变化。
还有一种情况是本人不能亲自来采模板，只有一张标准照片的情况下，也可以只用一个模板进行识别。
六．如何设置相似度阀值？
注：
下面的阀值是SDK的，对于最终用户，开发人员可以将这些阀值或相似度值“适当加大”输出。
当前版本的人脸检测推荐阀值为：
0.55
当前版本的人脸识别1CN推荐阀值为：
0.685
当前版本的人脸识别1C1推荐阀值为：
0.61
注意：
要想调到识别效果最佳，就在于视频或拍照的光线要打好，人脸肤色既不要太暗黑，也不要爆光过度，让人的整个眼球看上去很黑，眼白很白，（实际高清拍摄的眼球可能有点偏黄橙色,黄眼仁和黑瞳孔很分明，但这并非人脸识别实际需要的最好效果,不需要这种分明），总之使黑眼球在图像上显得鲜明突出，不论你如何换摄像头或调光，总之都要向着这个目标靠近。
如果是在户外识别，建议要加上遮光罩和镜头滤光片，以去除强阳光反射的干扰，目前实测柔和光线是最好的。
1.人脸识别或验证最好连续进行2次以上，取最大值，更可靠些。
（如果时间许可）
2.1C1由于有个人ID的输入或打卡，所以相似度阀值可略低些。
3.假定每个ID都有5个模板，且都有一张正面的BMP文件，则把所有加入的ID,用它们对应的BMP,在内部做一遍2选的1CN相互识别。
这样，2选的结果：
会输出两个值，第一个为张三的照片与张三的模板的相似度，第二个是与张三最像的人的模板与张三照片的相似度，我们关注第二个：
求出第二个的平均相似度及最高相似度，再参照SDK的推荐值来共同设定。
比如：
SDK的推荐值=0.55
全部互识别的第二个结果的平均相似度=0.2
第二个结果的最高相似度=0.41（由于这两个人像）
那么，说明：
最终阀值可定为：
0.55
虽然目前取0.43（比0.41多0.02）的阀值也不会出错，但难保外人来识别时不会错，所以还是用推荐值好些。
再比如：
SDK的推荐值=0.55
全部互识别的第二个结果的平均相似度=0.3
第二个结果的最高相似度=0.56（由于这两个人非常像）
那么，说明：
最终阀值可定为：
0.58（高于推荐值）否则：
这两个人就可能相互识别错。
七.图像格式，大小，人脸大小怎样最佳？
1.图像格式可用BMP,JPG,但最好用BMP,因为最终分析数据还是BMP的。
2.图像大小推荐用320*240（240*320更好），最大可支持1280*1280，但大了会使速度减慢。
3.人脸最佳采模板和识别SIZE是：
眼距40像素。
（两眼球中心连线的长度称为眼距）
八．产品的适用人群
仅对人脸识别而言：
（即不针对人脸检测）
最适用人群：
深色眼球，眉毛与眼睛界限分明，鼻尖处明暗分明。
不适用人群：
眼球颜色非常“浅色”的人脸。
（除此外，黑黄蓝绿眼球都是可以的）
年纪限制:
老少男女均可识别，无头发可，头发挡住眉毛也可。
佩戴限制:
戴墨镜不行，戴帽子可以，但不能挡住眼，戴粗黑边眼镜时，识别效果比不戴眼镜稍差，但仍能识别，其它眼镜不影响识别，而且可以戴眼镜采模板，不带眼镜识别，反之亦可。
只要看得清眼球即可，如果镜片反光，使眼球看不见了，这种情形是无法识别的。
九．人脸特征数据的保存
a）一个模板大约需要1MB的硬盘空间。
（注：
启用数据库压缩后会少用一大半）
其中含有一张档案式人脸照片，可由SDK函数读出并画出。
b）注意查看一个名为DataBase.ini的文件，里面可对数据库进行配置。
即可以由用户定制ADO连接串，目前主要兼容Access和SQLSERVER两种数据库。
（此项功能仅开放给多线程和开放式数据库接口的定制用户）
十．如何鉴别两套人脸识别SDK的优劣？
1CN如果识别出错（把你认成了别人），就意味着1C1也会错，即这个误认的人用你的ID号就能识别通过，所以，应用1CN来比较人脸识别开发包（SDK）的性能，几个人采好模板后，在各种可能性的光线下都能刚好通过的1CN阀值，就是“性能比较阀值”，（各家SDK的阀值不同，这就相当于让两个SDK都处于相同的识别能力水平上。
）然后想办法找百人照片，或千人照片，（且一个人只能有一张照片，不能重复,）越多越好，以每张照片一个ID的方式加入，从而构成大型人脸模板库，然后再一一用这些照片进行1CN的5选，当然第1名相似度应是0.99以上（自身像片），而第2，3，4，5个相似度（其他人的像片），应在“性能比较阀值”之下（否则就是实际上的认错人了），而且差距越大越好，然后统计出这1000次操作的平均结果，就可以知道哪个SDK识别能力强了。
十一．在DELPHI下做二次开发的注意事项：
a）因为是WIN32API,所以delphi调用应采用stdcall方式。
b）VC之CHAR*对应的变量类型是delphi的pchar类型。
c）定义结构时，应选择record方式。
十一.如何正确使用子功能：
用的子功能越多，速度就越慢，对于要求高速度的用户这就成了一个问题。
所以，对于人脸监控和录像的用户，只要做人脸检测即可，不用人眼定位等等。
对于虹膜识别的用户，只要做人脸检测，人眼定位，不用做面膜提取等等。
对于做面膜方面的用户，则无需进行眼镜检测及生成识别膜板。
前面的三项，每一项又都是后一项的基础。
所有子功能的开关，请参见下面函数部分。
十二.SDK升级信息
1.Ver2.7新增瞳孔定位功能，适用于高清照片的瞳孔定位或辅助虹膜识别。
2.Ver2.8人脸识别的鲁棒性优化，使能识别过去三年内的照片，识别速度提高20%。
3.Ver2.9人脸识别的光线自适应性能改良。
4.Ver2.92内存BUG的解决及相关操作说明文档的改进。
5.Ver2.95人工定位功能的加入，编译器优化编译，整体速度提高约15%。
6.Ver3.01人脸检测中曲度特征的加入，眼球定位再次改良。
7.Ver3.05侧脸识别小幅度改良。
8.Ver3.38复杂背景图像的处理速度改进；
三寸小照片的人脸检测、识别性能改进；
人脸检测误识率FER的大幅度下降。
9.Ver3.51在背光（逆光）环境下的人脸检测与识别的改进。
“三寸小照片”意义诠解：
类似二代身份证照片，宽度小于或等于160像素点的图像。
Width<=160
十三.人脸检测性能指标
1.人脸角度范围：
上仰30度，下俯30度，左侧30度，右侧30度，平面旋转60度。
2.光照范围：
太阳光，室内光，暗室，逆光。
3.人脸肤色范围：
黄色人种，白色人种，棕色人种，黑色人种，女士化妆。
4.其它支持：
模糊照片，变色照片，褪色照片，戴眼镜，戴帽。
5.图像大小：
最大1280*1280，推荐320*240，类型：
BMP/JPG。
最多可从一张图像中检出32张人脸。
6.人脸大小：
最小眼距8像素（开启小脸检测开关）或12像素，最大眼距160像素，推荐最佳眼距40像素。
眼距是指人脸上两眼中心连线的像素长度，可代表图像中的人脸大小。
下表是本SDK在人脸检测中的人脸大小限制:
图像宽度
最小眼距
最大眼距
图像宽度
最小眼距
最大眼距
1
小于200像素
大于12像素
小于图像宽度
4
541-800像素
大于16像素
小于140像素
2
200-360像素
大于16像素
小于120像素
5
801-1200像素
大于16像素
小于150像素
3
361-540像素
大于16像素
小于130像素
6
1200像素以上
大于16像素
小于160像素
上表只针对宽大于高的横向图像，对于高大于宽的纵向图像，只要眼距大于12像素而且小于图像宽度/2。
7.人脸检测正确率：
（1500张像片随机测试）:
99.5%,其中误识率0.01%,漏识率0.04%。
8.人脸检测速度：
图像大小320*240,CPU:
P42.4GHZ,平均速度<200ms/张。
第二部分
注1：
下文虽仅采用VC语言格式进行说明，但仍支持其它语言（VB,DELPHI,C#）进行二次开发。
注2：
一般地，本说明书的参数值（或返回值）LONG型的1表示真，表示开启，表示开关打开，0则表示假或关闭。
返回值是负数，表示有错发生，可以用GetLastError函数取得具体信息。
一．输出数据-结构定义：
//人脸检测的输出结果结构
structDLL_OUT_FACE_STRUCT
{
BYTEaddress;//无意义，传址的
LONGeye1_x;
LONGeye1_y;
LONGeye2_x;
LONGeye2_y;//两眼坐标,要进行了人眼定位才有效
//注意：
试用版不能做人眼定位,只能输出下面的人脸矩形。
LONGleft;
LONGtop;
LONGright;
LONGbottom;//人脸矩形
LONGangle;//人脸平面角度（正面垂直时为90度）
floattally;//得分,100分制,即人脸的置信度。
LONGis_small_face;//是小脸还是大脸，1为小脸，是启用了小脸检测的结果，小脸不能进行人脸识别
//当是小脸时，只输出人脸矩形，即只有人脸矩形有效,其它值无效
//下面的值要进行了人眼定位与人脸检测的后期处理才有效
LONGskin_color_R;//采样肤色COLORREF。
（RGB）
LONGskin_color_G;//采样肤色COLORREF。
（RGB）
LONGskin_color_B;//采样肤色COLORREF。
（RGB）
LONGskin_hd_bright;//采样肤色的灰度亮度。
LONGleft_face_len;//从左眼开始计算的左脸估计长度。
LONGright_face_len;//从右眼开始计算的右脸估计长度。
floatface_width_rely;//脸宽的信任度[0，1）。
LONGnose_x;//在原图像中的鼻尖位置。
LONGnose_y;//在原图像中的鼻尖位置。
floatnose_rely;//鼻尖位置:
可信任度[0，1）。
LONGmonth_x;//在原图像中的嘴中心位置。
LONGmonth_y;//在原图像中的嘴中心位置。
floatmonth_rely;//嘴心位置:
可信任度[0，1）。
floatglass_rely;//可能眼镜的置信度[0,1）。
LONGeye1_w;//人眼的两个眼球的宽与高,人眼的两个眼球的宽与高,但要求姿态端正，
LONGeye1_h;//定位精度随眼距的增大而增高
LONGeye2_w;
LONGeye2_h;
LONGCloseEyeBelievable;//闭眼的可能性系数输出,值域[0,1000]
//判断是睁眼还是闭眼，这个判断需要一定时长的序列连续CloseEyeBelievable数据才能统计分析出来。
};//ENDSTRUCTDEF
//1CN的识别输出结构
structDLL_1CN_RECOG_OUT_STRUCT
{
BYTEaddress;//无意义，传址的
floatvalue;//相似度值域（0,1）
charTemplate_ID[33];//模板的ID
charTemplateFileName[256];//模板源文件名称
};
二．SDK调用的-初始化部分
LONG__stdcallInitialize（CHAR*userkey）;//装入SDK时最先执行且只执行一次的。
//userkey或username，是作者发送给用户的一个字符串或密钥，输入正确，其它函数才能正确运行。
LONG__stdcallUnInitialize（）;//退出SDK时执行且只执行一次的。
LONG__stdcallGetLastError（LONGOID,CHAR*msg）;//取得最后一次失败的原因信息。
LONG__stdcallCreateOneThreadObject（LONGIS_LOAD_TZLIB=1,CHAR*DataFilePath=NULL）;
//参数1表示是否载入特征库到内存，只做慢速的1C1（或只做人脸检测）就不用LOAD.
//参数2表示指明数据文件的路径，数据与程序可以不在同一目录中，如果在同一目录，就默认为空。
//返回值，LONG线程对象的ID，线程ID值域[1,64],共可建64个线程,0表示失败
//如果是多线程，则此函数必要在线程上运行，即，
//一个对象实例，从头到尾都只能在一个线程上建立，运行，销毁。
LONG__stdcallDeleteOneThreadObject（LONGOID）;//返回值0，失败，1，成功
//销毁上一条函数建立的对象，回收内存
三．人脸识别主函数
//人脸定位的输出数组已按从高到低的得分排了序。
LONG__stdcallFaceLocate（LONGOID,//第一个函数返回的人脸识别实例对象ID
CHAR*FileName,//图像文件名，JPG,BMP
LONGmax_out_nums,//用户要求的最大人脸输出数
FLOATThreshold,//人脸置信度阀值，高于这个阀值才会被输出
DLL_OUT_FACE_STRUCT*dofs）;//人脸输出结构数组
//返回值，实际输出的人脸数量
LONG__stdcallFaceLocate_BmpData（LONGOID,//第一个函数返回的人脸识别实例对象ID
BYTE*BmpData,INTwidth,INTheight,INTbitcount,
//标准Windows位图数据（lpData,320,240,24）
LONGmax_out_nums,//用户要求的最大人脸输出数
FLOATThreshold,//人脸置信度阀值，高于这个阀值才会被输出
DLL_OUT_FACE_STRUCT*dofs）;//人脸输出结构数组
//返回值，实际输出的人脸数量,如果一张照片上有8张人脸，则返回8.
//注意：
如果max_out_nums参数设置为1，而实际的照片上有两个或更多人脸，则会仍只输出1个，但这个人脸是相似度得分最高的那个，往往这张人脸在照片中面积最大，姿态最端正，五官最清晰。
LONG__stdcallFlagFace（
LONGOID,LONGdraw_window_hwnd,LONGorder,LONGoffset_x=0,LONGoffset_y=0）;
//在目标窗口上标志人脸（用户也可自行开发本函数）
LONG__stdcallFaceLocate_FreeMemory（LONGOID）;（用户可自行开发）
//人脸检测完成后，会把一张人脸标准化小照片及一些参数保存在人脸输出结构中，作为人脸识别的数据源，
//或用于画一些人脸标志，当利用完毕后，即可用此命令回收内存。
LONG__stdcallRecog1C1（LONGOID,CHAR*VID,LONGorder,FLOAT*value,CHAR*TemplateFileName=NULL）;
LONG__stdcallRecog1C1_Fast
（LONGOID,CHAR*VID,LONGorder,FLOAT*value,CHAR*TemplateFileName=NULL）;
//VID是指当前检测到的人脸和模板库中的哪一个ID的脸做验证。
//order是人脸检测中输出的编号，order>=0order<人脸检测输出人脸数.
//比如说要对一张照片上检测出的8张人脸全都做识别，order从0到7，调用8次人脸验证或识别函数即可。
//value是本函数输出的相似度，值域[0，1）
//TemplateFileName请先预置256BYTE的空间，由于一个ID有多个模板，
//这里是输出与当前脸最像的模板的源图文件名称。
//FAST_1C1在速度上比1C1快并不是绝对的，当库中模板数越多时FAST_1C1会渐渐变慢，
//比如万人，或十万人，或更多，有可能FAST_1C1反而比1C1慢。
//因为1C1用的是标准SQL数据库查找模式（并比对TID对应的所有模板），
//而FAST_1C1用的是内存中逐一检索模式（只比对TID中最相似的两三个模板）。
LONG__stdcallRecog1CN（LONGOID,LONGorder,LONGmax_out_num,DLL_1CN_RECOG_OUT_STRUCT*dros）;
//order是人脸检测中输出的编号，order>=0order<输出人脸数.
//max_out_num是指输出多少个与ORDER相似的人脸，返回值就是实际输出数
//dros是输出结构
四．赠送的USB视频函数
LONG__stdcallUsbVideo_Init（LONGDEVICE_ID,LONGplay_window_hwnd）;//初始化
LONG__stdcallUsbVideo_CapOneBmp（CHAR*BmpFileName）;//捉一张bmp图像
LONG__stdcallUsbVideo_EndAll（）;//退出软件时调用
升级会员 