/Users/maurits/Documents/studie/afstuderen/biosphere/modules/fusion/bsmod_fusion.c

Go to the documentation of this file.

/*
 * Author: MA Hartman
 * Date: april 10, 2007
 * 
 * Function:
 * A module which offers multimodal biometric fusion at different levels.
 * 
 * License information:
 * 
 * Copyright (c) 2006 Maurits Hartman
 *
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use,
 * copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following
 * conditions:
 * 
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
 * 
 */

#include <biosphere_module.h>
#include "util.h"

#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>
#include <math.h>

#define NORM_METHOD_NO 0        
#define NORM_METHOD_MM 1        
#define NORM_METHOD_ZS 2        
#define NORM_METHOD_TH 3        
#define NORM_METHOD_QQ 4        
#define NORM_METHOD_QLQ 5       
bs_module bsmod_symtable;


static bs_status bsmod_fusion_init(void)
{
        return BS_OK;
}


static bs_status bsmod_fusion_cleanup(void)
{
        return BS_OK;   
}


static bs_service_response *create_biometric_decision_response(
                const bs_service_request *request,
                bs_bool decision)
{
        bs_service_response *resp;
        bs_message_instance *output;
        bs_part_instance *part;
        bs_data_type *type;
        unsigned i;
        
        resp = (bs_service_response *) calloc(1, sizeof(bs_service_response));
        for (i = 0; i < 16; i++)
                resp->uuid[i] = request->uuid[i];
        resp->service = (char *) malloc(len(request->service) + 1);
        resp->port = (char *) malloc(len(request->port) + 1);
        resp->operation = (char *) malloc(len(request->operation) + 1);
        strcpy(resp->service, request->service);
        strcpy(resp->port, request->port);
        strcpy(resp->operation, request->operation);
        
        output = (bs_message_instance *) calloc(1, sizeof(bs_service_response));
        output->name = (char *) malloc(len("biometric_decision") + 1);
        strcpy(output->name, "biometric_decision");
        output->num_parts = 1;
        output->parts = (bs_part_instance **) calloc(1, sizeof(bs_part_instance *));
        resp->output = output;
        
        part = (bs_part_instance *) calloc(1, sizeof(bs_part_instance));
        part->name = (char *) malloc(len("") + 1);
        strcpy(part->name, "decision");
        part->data = (char *) calloc(1, 20);
        if (decision) sprintf(part->data, "ACCEPT");
        else sprintf(part->data, "REJECT");
        part->size = len(part->data); 
        output->parts[0] = part;
        
        type = (bs_data_type *) calloc(1, sizeof(bs_data_type));
        type->name = (char *) malloc(len("bs_string") + 1);
        strcpy(type->name, "bs_string");
        type->builtin = TRUE;
        type->from_mp = FALSE;
        part->type = type;
        
        return resp;
}


static bs_service_response *create_biometric_response(
                const bs_service_request *request,
                bs_double score)
{
        bs_service_response *resp;
        bs_message_instance *output;
        bs_part_instance *part;
        bs_data_type *type;
        unsigned i;
        
        resp = (bs_service_response *) calloc(1, sizeof(bs_service_response));
        for (i = 0; i < 16; i++)
                resp->uuid[i] = request->uuid[i];
        resp->service = (char *) malloc(len(request->service) + 1);
        resp->port = (char *) malloc(len(request->port) + 1);
        resp->operation = (char *) malloc(len(request->operation) + 1);
        strcpy(resp->service, request->service);
        strcpy(resp->port, request->port);
        strcpy(resp->operation, request->operation);
        
        output = (bs_message_instance *) calloc(1, sizeof(bs_service_response));
        output->name = (char *) malloc(len("biometric_score") + 1);
        strcpy(output->name, "biometric_score");
        output->num_parts = 1;
        output->parts = (bs_part_instance **) calloc(1, sizeof(bs_part_instance *));
        resp->output = output;
        
        part = (bs_part_instance *) calloc(1, sizeof(bs_part_instance));
        part->name = (char *) malloc(len("") + 1);
        strcpy(part->name, "score");
        part->data = (char *) calloc(1, 20);
        sprintf(part->data, "%lf", score);
        part->size = len(part->data); 
        output->parts[0] = part;
        
        type = (bs_data_type *) calloc(1, sizeof(bs_data_type));
        type->name = (char *) malloc(len("bs_double") + 1);
        strcpy(type->name, "bs_double");
        type->builtin = TRUE;
        type->from_mp = FALSE;
        part->type = type;
        
        return resp;
}


static int get_normalization(const char *norm)
{
        if (strlen(norm) < 2) return NORM_METHOD_NO;
        if (norm[0] == 'M' && norm[1] == 'M') return NORM_METHOD_MM;
        if (norm[0] == 'Z' && norm[1] == 'S') return NORM_METHOD_ZS;
        if (norm[0] == 'T' && norm[1] == 'H') return NORM_METHOD_TH;
        if (norm[0] == 'Q' && norm[1] == 'Q') return NORM_METHOD_QQ;
        if (norm[0] == 'Q' && norm[1] == 'L' && norm[2] == 'Q')
                return NORM_METHOD_QLQ;
        else return NORM_METHOD_NO;     
}

#define IMPOSSIBLE 1000000000.0

static double normalize(double s, char *norm)
{
        int normtype = get_normalization(norm);
        double p1 = IMPOSSIBLE, p2 = IMPOSSIBLE;
        double c = IMPOSSIBLE, w = IMPOSSIBLE, Nmm;
        unsigned i = 1;
        
        if (normtype == NORM_METHOD_NO) return s;
        
        /* Retrieve the parameters (two or four): */
        while (norm[i] != '\0') {
                if (norm[i-1] == ' ' && norm[i] != ' ') {
                        char *n = norm + i;
                        p1 = atof(n);
                        i++;
                        break;
                }
                i++;    
        }
        while (norm[i] != '\0') {
                if (norm[i-1] == ' ' && norm[i] != ' ') {
                        char *n = norm + i;
                        p2 = atof(n);
                        i++;
                        break;
                }
                i++;    
        }
        while (norm[i] != '\0') {
                if (norm[i-1] == ' ' && norm[i] != ' ') {
                        char *n = norm + i;
                        c = atof(n);
                        i++;
                        break;
                }
                i++;    
        }
        while (norm[i] != '\0') {
                if (norm[i-1] == ' ' && norm[i] != ' ') {
                        char *n = norm + i;
                        w = atof(n);
                        i++;
                        break;
                }
                i++;    
        }
        if (p1 == IMPOSSIBLE || p2 == IMPOSSIBLE) return -1.0;
        
        /* Calculate different normalizations: */
        switch(normtype) {
                case NORM_METHOD_MM:
                        /* p1 = min, p2 = max, map linearly to [0,1]: */
                        return (s - p1) / (p2 - p1);
                case NORM_METHOD_ZS:
                        /* p1 = mean, p2 = stdev: */
                        return (s - p1) / p2;
                case NORM_METHOD_TH:
                        /* p1 = mean, p2 = stdev: */
                        return 0.5 * (tanh(0.01 * (s - p1) / p2) + 1);
                case NORM_METHOD_QQ:
                        /* QQ function with Min-Max mapping (Nmm) to [0,1]: */
                        if (c == IMPOSSIBLE) return -1.0;
                        Nmm = (s - p1) / (p2 - p1);
                        if (Nmm <= c) return Nmm * Nmm / c;
                        else return c + sqrt((1 - c) * (Nmm - c));
                case NORM_METHOD_QLQ:
                        /* Similar to QQ, but with overlapped zone w: */
                        if (c == IMPOSSIBLE || w == IMPOSSIBLE) return -1.0;
                        Nmm = (s - p1) / (p2 - p1);
                        if (Nmm <= c - w/2) return Nmm * Nmm / (c - w/2);
                        else if (c - w/2 < Nmm && Nmm <= c + w/2) return Nmm;
                        else return c + w/2 + sqrt((1 - c - w/2) * (Nmm - c - w/2));
        }
        return s;
}


static double fuse_mw(unsigned ns, double s1, double s2, double s3,
                char *meth)
{
        double w1 = IMPOSSIBLE, w2 = IMPOSSIBLE, w3 = IMPOSSIBLE;
        unsigned i = 1;
        
        while (meth[i] != '\0') {
                if (meth[i-1] == ' ' && meth[i] != ' ') {
                        char *n = meth + i;
                        w1 = atof(n);
                        i++;
                        break;
                }
                i++;    
        }
        while (meth[i] != '\0') {
                if (meth[i-1] == ' ' && meth[i] != ' ') {
                        char *n = meth + i;
                        w2 = atof(n);
                        i++;
                        break;
                }
                i++;    
        }
        while (meth[i] != '\0') {
                if (meth[i-1] == ' ' && meth[i] != ' ') {
                        char *n = meth + i;
                        w3 = atof(n);
                        i++;
                        break;
                }
                i++;    
        }
        
        if (ns == 2 && w1 != IMPOSSIBLE && w2 != IMPOSSIBLE) {
                double mw1, mw2;
                mw1 = 1.0 / (w1 * (1/w1 + 1/w2));
                mw2 = 1.0 / (w2 * (1/w1 + 1/w2));
                return s1 * mw1 + s2 * mw2;
        }
        else if (ns == 3 && w1 != IMPOSSIBLE && w2 != IMPOSSIBLE &&
                        w3 != IMPOSSIBLE) {
                double mw1, mw2, mw3;
                mw1 = 1.0 / (w1 * (1/w1 + 1/w2 + 1/w3));
                mw2 = 1.0 / (w2 * (1/w1 + 1/w2 + 1/w3));
                mw3 = 1.0 / (w3 * (1/w1 + 1/w2 + 1/w3));
                return s1 * mw1 + s2 * mw2 + s3 * mw3;
        }
        return -1.0;    
}

static bs_bool fuse_dw(unsigned ns, bs_bool s1a, bs_bool s2a, bs_bool s3a,
                char *meth)
{
        double s1 = s1a ? 1.0: 0.0;
        double s2 = s2a ? 1.0: 0.0;
        double s3 = s3a ? 1.0: 0.0;
        double threshold;
        
        double w1 = IMPOSSIBLE, w2 = IMPOSSIBLE, w3 = IMPOSSIBLE;
        unsigned i = 1;
        
        /* Extract parameters: */
        while (meth[i] != '\0') {
                if (meth[i-1] == ' ' && meth[i] != ' ') {
                        char *n = meth + i;
                        threshold = atof(n);
                        i++;
                        break;
                }
                i++;    
        }
        while (meth[i] != '\0') {
                if (meth[i-1] == ' ' && meth[i] != ' ') {
                        char *n = meth + i;
                        w1 = atof(n);
                        i++;
                        break;
                }
                i++;    
        }
        while (meth[i] != '\0') {
                if (meth[i-1] == ' ' && meth[i] != ' ') {
                        char *n = meth + i;
                        w2 = atof(n);
                        i++;
                        break;
                }
                i++;    
        }
        while (meth[i] != '\0') {
                if (meth[i-1] == ' ' && meth[i] != ' ') {
                        char *n = meth + i;
                        w3 = atof(n);
                        i++;
                        break;
                }
                i++;    
        }
        
        if (ns == 2 && w1 != IMPOSSIBLE && w2 != IMPOSSIBLE) {
                double mw1, mw2;
                mw1 = 1.0 / (w1 * (1/w1 + 1/w2));
                mw2 = 1.0 / (w2 * (1/w1 + 1/w2));
                return s1 * mw1 + s2 * mw2 >= threshold;
        }
        else if (ns == 3 && w1 != IMPOSSIBLE && w2 != IMPOSSIBLE &&
                        w3 != IMPOSSIBLE) {
                double mw1, mw2, mw3;
                mw1 = 1.0 / (w1 * (1/w1 + 1/w2 + 1/w3));
                mw2 = 1.0 / (w2 * (1/w1 + 1/w2 + 1/w3));
                mw3 = 1.0 / (w3 * (1/w1 + 1/w2 + 1/w3));
                return s1 * mw1 + s2 * mw2 + s3 * mw3 >= threshold;
        }
        return FALSE;
}


static bs_bool majority_vote(unsigned ns, double s1, double s2, double s3,
                char *meth)
{
        double threshold = 1.5;
        unsigned i = 1, num_accept = 0;
        
        /* Extract parameters: */
        while (meth[i] != '\0') {
                if (meth[i-1] == ' ' && meth[i] != ' ') {
                        char *n = meth + i;
                        threshold = atof(n);
                        i++;
                        break;
                }
                i++;    
        }
        
        /* Count accept votes: */
        if (s1) num_accept++;
        if (s2) num_accept++;
        if (ns > 2 && s3) num_accept++;
        return num_accept >= threshold;
}


static bs_status handle_fuse2(const bs_service_request *request,
                bs_service_response **response)
{
        char *meth, *norm1, *norm2;
        double s1, s2, result = -1.0;
        
        /* Get parts: */
        if (request->input->num_parts != 5) return BS_SERVICE_NUM_PARTS_MISMATCH;
        meth = request->input->parts[0]->data;
        if (strlen(meth) < 2) return BS_SERVICE_PART_INCORRECT;
        norm1 = request->input->parts[1]->data;
        norm2 = request->input->parts[2]->data;
        s1 = atof(request->input->parts[3]->data);
        s2 = atof(request->input->parts[4]->data);
        
        /* Normalize the scores: */
        s1 = normalize(s1, norm1);
        s2 = normalize(s2, norm2);
        
        /* Calculate fusion: */
        if (meth[0] == 'S' && meth[1] == 'S')
                result = s1 + s2;
        else if (meth[0] == 'M' && meth[1] == 'I')
                result = min(s1, s2, 10000000.0); /* TODO A tad unsafe... */
        else if (meth[0] == 'M' && meth[1] == 'A')
                result = max(s1, s2, -10000000.0); /* TODO A tad unsafe... */
        else if (meth[0] == 'M' && meth[1] == 'W')
                result = fuse_mw(2, s1, s2, 0.0, meth);
        
        /* Create response: */
        *response = create_biometric_response(request, result);
        return BS_OK;
}


static bs_status handle_fuse3(const bs_service_request *request,
                bs_service_response **response)
{
        char *meth, *norm1, *norm2, *norm3;
        double s1, s2, s3, result = -1.0;
        
        /* Get parts: */
        if (request->input->num_parts != 7) return BS_SERVICE_NUM_PARTS_MISMATCH;
        meth = request->input->parts[0]->data;
        if (strlen(meth) < 2) return BS_SERVICE_PART_INCORRECT;
        norm1 = request->input->parts[1]->data;
        norm2 = request->input->parts[2]->data;
        norm3 = request->input->parts[3]->data;
        s1 = atof(request->input->parts[4]->data);
        s2 = atof(request->input->parts[5]->data);
        s3 = atof(request->input->parts[6]->data);
        
        /* Normalize the scores: */
        s1 = normalize(s1, norm1);
        s2 = normalize(s2, norm2);
        s3 = normalize(s3, norm3);
        
        /* Calculate fusion: */
        if (meth[0] == 'S' && meth[1] == 'S')
                result = s1 + s2 + s3;
        else if (meth[0] == 'M' && meth[1] == 'I')
                result = min(s1, s2, s3);
        else if (meth[0] == 'M' && meth[1] == 'A')
                result = max(s1, s2, s3);
        else if (meth[0] == 'M' && meth[1] == 'W')
                result = fuse_mw(3, s1, s2, s3, meth);
        
        /* Create response: */
        *response = create_biometric_response(request, result);
        return BS_OK;
}


static bs_status handle_fuse2_decision(const bs_service_request *request,
                bs_service_response **response)
{
        char *meth;
        bs_bool s1, s2, result = FALSE;
        
        /* Get parts: */
        if (request->input->num_parts != 3) return BS_SERVICE_NUM_PARTS_MISMATCH;
        meth = request->input->parts[0]->data;
        if (strlen(meth) < 2) return BS_SERVICE_PART_INCORRECT;
        s1 = decision_to_bool(request->input->parts[1]->data);
        s2 = decision_to_bool(request->input->parts[2]->data);
        
        
        /* Calculate fusion: */
        if (meth[0] == 'B' && meth[1] == 'A') {/* Boolean And */
                if (s1 && s2) result = TRUE;
        }
        else if (meth[0] == 'B' && meth[1] == 'O') {/* Boolean Or */
                if (s1 || s2) result = TRUE;
        }
        else if (meth[0] == 'M' && meth[1] == 'V') /* Majority voting */
                result = majority_vote(2, s1, s2, FALSE, meth);
        else if (meth[0] == 'D' && meth[1] == 'W') /* Decision weighting */
                result = fuse_dw(2, s1, s2, FALSE, meth);
        else return BS_ERROR;
        
        /* Create response: */
        *response = create_biometric_decision_response(request, result);
        return BS_OK;
}


static bs_status handle_fuse3_decision(const bs_service_request *request,
                bs_service_response **response)
{
        char *meth;
        bs_bool s1, s2, s3, result = FALSE;
        
        /* Get parts: */
        if (request->input->num_parts != 4) return BS_SERVICE_NUM_PARTS_MISMATCH;
        meth = request->input->parts[0]->data;
        if (strlen(meth) < 2) return BS_SERVICE_PART_INCORRECT;
        s1 = decision_to_bool(request->input->parts[1]->data);
        s2 = decision_to_bool(request->input->parts[2]->data);
        s3 = decision_to_bool(request->input->parts[3]->data);
        
        
        /* Calculate fusion: */
        if (meth[0] == 'B' && meth[1] == 'A') {/* Boolean And */
                if (s1 && s2 && s3) result = TRUE;
        }
        else if (meth[0] == 'B' && meth[1] == 'O') {/* Boolean Or */
                if (s1 || s2 || s3) result = TRUE;
        }
        else if (meth[0] == 'M' && meth[1] == 'V') /* Majority voting */
                result = majority_vote(3, s1, s2, s3, meth);
        else if (meth[0] == 'D' && meth[1] == 'W') /* Decision weighting */
                result = fuse_dw(3, s1, s2, s3, meth);
        else return BS_ERROR;
        
        /* Create response: */
        *response = create_biometric_decision_response(request, result);
        return BS_OK;
}


static bs_status bsmod_fusion_handle_service(
                const bs_service_request *request,
                bs_service_response **response, void *extra)
{
        if (!streq(request->service, "BSModFusionServices"))
                return BS_NO_SERVICE;
        
        if (streq(request->port, "MatchLevel")) {
                if (streq(request->operation, "fuse2"))
                        return handle_fuse2(request, response);
                else if (streq(request->operation, "fuse3"))
                        return handle_fuse3(request, response);
        }
        else if (streq(request->port, "DecisionLevel")) {
                if (streq(request->operation, "fuse2_decision"))
                        return handle_fuse2_decision(request, response);
                else if (streq(request->operation, "fuse3_decision"))
                        return handle_fuse3_decision(request, response);
        }
        
        return BS_NO_SERVICE;                   
}


/* Here come functions offered by the module: */

/* Final declaration of the bs_module struct: */
bs_module bsmod_symtable = {
        /* The major and minor version of the API used by this module: */
        0,
        0,
        
        /* The major and minor version of this module: */
        0,
        1,
        
        /* The name, author, date and copyright information: */
        "multimodal fusion module",
        "M.A.Hartman",
        "may 5, 2007",
        "(c) 2007, M.A.Hartman. See distributed LICENSE file for more information.",
        "A module which offers various biometric fusion functions and normalization "
        "methods. Fusion methods are: Simple Sum (SS), Minimum Score (MI), "
        "Maximum Score (MA) and Matcher Weighting (MW). Available normalization "
        "that can be applied to the score before fusion are: Min-Max (MM), Z-score (ZS), "
        "Tanh (TH) and Adaptive (QQ and QLQ). Some of the normalization functions "
        "require extra parameters. These should be provided after the name of the "
        "normalization, separated by spaces, in the 'norm' part.",
        
        /* Init and cleanup routines: */
        bsmod_fusion_init,
        bsmod_fusion_cleanup,
        
        /* Service request handling function: */
        bsmod_fusion_handle_service,
        NULL,
        "bsmod_fusion.wsdl"
};

---