001package net.gdface.sdk.fse;
002
003import net.gdface.annotation.DeriveMethod;
004
005/**
006 * 特征码内存搜索引擎(feature search engine)接口<br>
007 * 提供高速的人脸特征相似度比对搜索/排序,支持多线程并行搜索，适用于百万级以上人脸库的快速搜索。<br>
008 * 1.使用 {@link #addFeature(byte[], byte[], String)}方法将特征添加到搜索引擎<br>
009 * 2.使用 {@link #searchCode(byte[], double, int)}在内存中搜索与指定特征相似的的特征返回搜索结果
010 * @author guyadong
011 *
012 */
013public interface FeatureSe {
014        /**
015         *      在内存表中根据比对相似度进行特征码搜索
016         * @param code 要比对的特征码
017         * @param sim 相似度阀值
018         * @param rows  最大返回的记录数
019         * @return 返回包含相似度(降序)的结果数组,如果没有查到匹配的记录则返回空数组
020         */
021        @DeriveMethod(methodSuffix="FromFse")
022        public CodeBean[] searchCode(byte[] code, double sim, int rows);
023        /**
024         * 根据特征码ID在表中查找指定的记录
025         * @param featureId 特征码ID,MD5校验码(16 bytes)
026         * @return 返回指定的特征记录,没有找到则返回{@code null},{@code featureId}为{@code null}或空返回{@code null}
027         */
028        @DeriveMethod(methodSuffix="FromFse")
029        public CodeBean getFeature(byte[] featureId);
030        /**
031         * 根据特征码ID在表中查找指定的记录
032         * @param featureId 特征码ID,MD5校验码(32字节HEX字符串)
033         * @return 返回指定的特征记录,没有找到则返回{@code null},{@code featureId}为{@code null}或空返回{@code null}
034         */
035        @DeriveMethod(methodSuffix="FromFse")
036        public CodeBean getFeatureByHex(String featureId);
037        /**
038         * 添加一条特征码到内存表<br>
039         * @param featureId 特征码ID(MD5校验码),为null时,native library会自动计算MD5作为特征码ID
040         * @param feature 特征码字节数组,为{@code null}时返回false
041         * @param imgMD5 特征所属图的MD5(32字节HEX字符串),可为null
042         * @return 添加成功返回true, 否则返回false
043         */
044        @DeriveMethod(methodSuffix="ToFse")
045        public boolean addFeature(byte[] featureId,byte[]feature, String imgMD5);
046        /**
047         * 添加一条特征码到内存表<br>
048         * @param featureId 特征码ID(MD5校验码),为null时,native library会自动计算MD5作为特征码ID
049         * @param feature 特征码字节数组,为{@code null}时返回false
050         * @param appid 应用id,由调用者定义,可为null
051         * @return 添加成功返回true, 否则返回false
052         */
053        @DeriveMethod(methodSuffix="ToFseWithAppId")
054        boolean addFeature(byte[] featureId, byte[] feature, long appid);
055        /**
056         * 根据特征码ID中表中删除指定的记录
057         * @param featureId  特征码ID,MD5校验码(16 bytes)
058         * @return 成功删除则返回true,否则返回false
059         */
060        @DeriveMethod(methodSuffix="FromFse")
061        public boolean removeFeature(byte[] featureId);
062        /**
063         * 根据特征码ID中表中删除指定的记录
064         * @param featureId 特征码ID,MD5校验码(32字节HEX字符串)
065         * @return 成功删除则返回true,否则返回false
066         */
067        @DeriveMethod(methodSuffix="FromFse")
068        public boolean removeFeatureByHex(String featureId);
069        /**
070         * 删除内存表中所有特征数据
071         */
072        @DeriveMethod(methodSuffix="OfFse")
073        public void clearAll();
074        /**
075         * 
076         * @return 内存表中元素个数
077         */
078        @DeriveMethod(methodSuffix="OfFse")
079        public int size();
080}