The BQ3287 model by itself is really easy to interface with MCUs. There is a nice tutorial on how to use BQ3287 with Arduino and some of the code I am using in this post is borrowed from that project. The main difficulty of turning BQ3287 into a full-fledged clock is that this RTC module uses up to 16 digital pins out of 20 usable pins an ATMega328p has, which leaves very few pins for display and control purposes. After toying with a few possible designs, I decided to use 13 out of the 16 pins so that no major functionality is sacrificed (MOT is left disconnected using Intel bus timing, RESET is tied to Vcc and CS is connected to ground).

Digital pin 0 and 1 (chip pin 1 and 2) are used for button input. Since these two pins are also used as serial RX TX pair when used with the Arduino (the FT232RL chip communicates to The ATmega328 via these two pins) board, I resorted to the ICSP method to program the chip without using the Arduino board.

With this setup, we have two additional pins (pin 27 and 28, these are analog pin 4 and 5 on the Arduino board) available. Since these two pin s are the SCL and SDA pins in TWI (I2C) communication, I am planning to use them to communicate to another ATmega328 chip to further expand the functionality of this clock in the future.

For now, I am using the two buttons to multiplex the following functions:

• Display Time
• Display Date
• Display Year
• Stop Watch
• Change Time Setting
• Change Date Setting
• Change Year Setting

Please see the comment in the code section below to see how these functionalities are achieved.

Three pins are used to control the 4 7 segment display I made earlier. The display update is triggered by the interrupt signal generated from the SQW output pin of BQ3287, I set the interrupt frequency to 128 Hz (RS3 RS2 RS1 RS0 = 1001) to ensure the accuracy of the stop watch (0.1 second) while still maintain a reasonable overhead. The update code all resides in the interrupt handler (intr()).

As you can see in the code, dot between the hour and minute display is turned on and off on a half second interval and in change settings mode the values to be changed also flashes at a half second interval.

Here are some pictures showing the clock displaying in various modes. And the last picture shows the board setup: the front board houses the 4 7 segment display, the left side is the ATmega328 board, the middle one contains the BQ3287 module and the right side board is the voltage regulator board. I used a Taxes Instrument TL720M05 LDO linear voltage regulator, which is a nice LDO pin compatible replacement of the good old 7805.

Time	Date
Year	Day of the Week (Thursday)
Stop Watch	The Setup

And here’s the code listing for this project. As mentioned earlier, I am planing to use a separate ATmega328 board to communicate with this clock using TWI so that I can setup timers/alarms to control other electronics.

//define the bidirectional address-data bus
const int ad0 = 3; //chip pin 5
const int ad1 = 4; //chip pin 6
const int ad2 = 5; //chip pin 11
const int ad3 = 6; //chip pin 12
const int ad4 = 7; //chip pin 13
const int ad5 = 8; //chip pin 14
const int ad6 = 9; //chip pin 15
const int ad7 = 10; //chip pin 16

//ALE or address strobe (AS pin)
const int as = 11; //chip pin 17
//WR or (RW pin)
const int rw = 12; //chip pin 18
//RD or OE (DS pin )
const int ds = 13; //chip pin 19
//interrupt request
const int irq = 14; //chip pin 23

//7-seg display pins
const int clockPin = 15; //chip pin 24
const int latchPin = 16; //chip pin 25
const int dataPin = 17; //chip pin 26

//control button pins
//Note, since these are the rx/tx pins when using FT232RL
//you will either have to program the chip using a programmer (the method I used)
//or using the remaining two two analog data pins (18 and 19). But then you are
//lossing two pins to work with.
const int btnPin1 = 0; //chip pin 1
const int btnPin2 = 1; //chip pin 2

const int COMMON_ANODE = 1; //1 CA, 0 CC

//bq3287 registers
const int regA = 0x0A;
const int regB = 0x0B;

//RO registers C,D
const int regC = 0x0C;
const int regD = 0x0D;

const int ADDR_CUR_SEC = 0;
const int ADDR_ALM_SEC = 1;
const int ADDR_CUR_MIN = 2;
const int ADDR_ALM_MIN = 3;
const int ADDR_CUR_HOUR = 4;
const int ADDR_ALM_HOUR = 5;
const int ADDR_CUR_DOW = 6;
const int ADDR_CUR_DAY = 7;
const int ADDR_CUR_MON = 8;
const int ADDR_CUR_YEAR = 9;

//display modes
//button 1 has 4 modes
const int DM_TIME = 0; //display time
const int DM_DATE = 1; //display date
const int DM_YEAR = 2; //display year
const int DM_DOW = 3; //display day of the week
const int DM_STOP_WATCH = 4; //display stop watch

//button 2 has 7 modes
const int DM_ADJ_NONE = 0; //display the current time
const int DM_ADJ_HOUR = 1; //adjust hour
const int DM_ADJ_MIN = 2; //adjust minute
const int DM_ADJ_MONTH = 3; //adjust month
const int DM_ADJ_DAY = 4; //adjust day
const int DM_ADJ_YEAR = 5; //adjust year
const int DM_ADJ_DOW = 6; //adjust day of the week

/** global variables for storing button's current mode.
 * Button functions
 * When button 2 is not pressed (in DM_ADJ_NONE)
 * press button 1 will cycle through the following display modes:
 *      current time (default)
 *      current date
 *      current year
 *      stop watch
 * when in stop watch mode, button 1 is used to start/stop/reset the stop watch.
 *
 * while in display current time mode (button 1 mode equals DM_TIME)
 * press button 2 will cycle through the following adjustment modes:
 *      adjust hour
 *      adjust minute
 *      adjust month
 *      adjust day
 *      adjust year
 *      adjust day of week
 * when in adjustment mode, button 1 is used to increment the settings.
 */
int btnMode1 = 0;
int btnMode2 = 0;

boolean btn1Pressed = false;
boolean btn2Pressed = false;

//stop watch initialization indicator, if this is set to true
//the stop watch is stopped and displays 0.0
boolean stopWatchInit = true;
boolean stopWatchStarted = false;

/** 7seg character mapping char <-> code */
struct CharMap {
    char c;
    byte v;
};

//the length of the character map, it must match
//the cmap[] array lengh below
const int cmap_len = 41;

//defines the 7seg display characters
struct CharMap cmap[] = {
    {' ', 0},
    {'1', 96},
    {'2', 218},
    {'3', 242},
    {'4', 102},
    {'5', 182},
    {'6', 190},
    {'7', 224},
    {'8', 254},
    {'9', 246},
    {'0', 252},
    {'A', 238},
    {'b', 62},
    {'c', 26},
    {'C', 156},
    {'d', 122},
    {'e', 222},
    {'E', 158},
    {'F', 142},
    {'g', 246},
    {'H', 110},
    {'h', 46},
    {'I', 96},
    {'J', 120},
    {'L', 28},
    {'n', 42},
    {'o', 58},
    {'P', 206},
    {'q', 230},
    {'r', 10},
    {'S', 182},
    {'t', 30},
    {'u', 56},
    {'U', 124},
    {'y', 118},
    {'-', 2},
    {'~', 128},
    {'_', 16},
    {'.', 1},
    {'|', 108},
    {'=', 144}
};

//indicates whether the led on 7seg indicating the "seconds" is on
boolean secondIndLEDOn = false;

//arrays for date/time conversion
char hour[2], minute[2], seconds[6];
char year[2], month[2], day[2], dow[1];

//the 4 characters on the 7seg
char c1, c2, c3, c4;

//this counter is incremented whenever the SW output pin
//triggers the interrupt
int interruptConter = 0;

//this counter is used to keep track of time in stop watch mode
unsigned int stopWatchCounter = 0;

/** same as delay() but works with interrupts */
void delayMilliseconds(int ms) {
    for (int i = 0; i < ms; i++) {
        delayMicroseconds(1000);
    }
}

/** get the display code for a character
/* it looks through the charactor map and find a match that corresponds to c
/* if no match is found, it returns 2 (corresponding to character '-') */
byte getCharDisplayCode(char c) {
    byte r = 2;

    for (int i = 0; i < cmap_len; i++) {
        if (c == cmap[i].c) {
            r = cmap[i].v;
            break;
        }
    }

    return r;
}

/** initialize the display
/* when the 7seg display is initialized, display nothing */
void init7seg() {
    pinMode(latchPin, OUTPUT);
    pinMode(clockPin, OUTPUT);
    pinMode(dataPin, OUTPUT);

    disp(' ', false, ' ', false, ' ', false, ' ', false);
}

/** this essentially is the library function shiftOut, it can be customized if
/* it is needed.
/* it works with 74HC595 (serial in, parallel out) */
void shiftOut(uint8_t dataPin, uint8_t clockPin, byte val) {
    int i;

    for (i = 0; i < 8; i++) {
        digitalWrite(dataPin, (val & _BV(i)));
        digitalWrite(clockPin, HIGH);
        digitalWrite(clockPin, LOW);
    }
}

/* display the characters on the 7seg
/* the boolean value between characters indicates whether to light up the
/* decimal point */
void disp(char c1, boolean dot1, char c2, boolean dot2, char c3, boolean dot3, char c4, boolean dot4) {
    byte b1 = getCharDisplayCode(c1);
    byte b2 = getCharDisplayCode(c2);
    byte b3 = getCharDisplayCode(c3);
    byte b4 = getCharDisplayCode(c4);

    if (dot1 == true) b1 += 1;
    if (dot2 == true) b2 += 1;
    if (dot3 == true) b3 += 1;
    if (dot4 == true) b4 += 1;

    if (COMMON_ANODE == 1) {
        b1 = 255 - b1;
        b2 = 255 - b2;
        b3 = 255 - b3;
        b4 = 255 - b4;
    }

    digitalWrite(latchPin, LOW);

    shiftOut(dataPin, clockPin, b4);
    shiftOut(dataPin, clockPin, b3);
    shiftOut(dataPin, clockPin, b2);
    shiftOut(dataPin, clockPin, b1);

    digitalWrite(latchPin, HIGH);
}

/** convert a number (maximum 2 digita) to a character array
/* returning the length of the converted char array
/* this is used to convert hour/minutes into characters for display */
int convertToCharAarray(byte num, char *dest) {
    sprintf(dest, "%d", num);

    if (num < 10) return 1;
    else if (num < 100 && num >= 10) return 2;
    else return -1;
}

/** displays the current time on 7seg,
/* the display mode is controlled by the states of the button states */
void dispCurrentTime() {
    if (!bitRead(readbyte(regA), 7)) {
        byte h = readbyte(ADDR_CUR_HOUR);
        byte m = readbyte(ADDR_CUR_MIN);

        byte l1 = convertToCharAarray(h, hour);
        byte l2 = convertToCharAarray(m, minute);

        if (l1 == 1) {
            c2 = ' ';
            c1 = hour[0];
        } else {
            c1 = hour[1];
            c2 = hour[0];
        }

        if (l2 == 1) {
            c4 = '0';
            c3 = minute[0];
        } else {
            c3 = minute[1];
            c4 = minute[0];
        }
    }

    disp(c2, false, c1, secondIndLEDOn, c4, false, c3, false);

    switch (btnMode2) {
        case DM_ADJ_NONE: //normal display mode, displays time
            disp(c2, false, c1, secondIndLEDOn, c4, false, c3, false);
            break;
        case DM_ADJ_HOUR: //if adjust hour, flash the hour digits
            if (secondIndLEDOn)
                disp(' ', false, ' ', true, c4, false, c3, false);
            else
                disp(c2, false, c1, true, c4, false, c3, false);
            break;
        case DM_ADJ_MIN: //if adjust minutes, flash the minute digits
            if (secondIndLEDOn)
                disp(c2, false, c1, true, ' ', false, ' ', false);
            else
                disp(c2, false, c1, true, c4, false, c3, false);
            break;
    }
}

/** displays in stop watch mode. */
void dispStopWatch() {
    for (int i = 0; i < 5; i++) seconds[i] = ' ';

    int i = (int) (((float) (stopWatchCounter) / 128.0) * 10.0 + 0.5);
    sprintf(seconds, "%6d", i);

    if (stopWatchInit) {
        disp(' ', false, ' ', false, '0', true, '0', false);
    } else {
        if (stopWatchCounter < 128) { //less than 1 second, displays the leading 0
            disp(seconds[2], false, seconds[3], false, '0', true, seconds[5], false);
        } else {
            disp(seconds[2], false, seconds[3], false, seconds[4], true, seconds[5], false);
        }
    }
}

/** displays current date */
void dispCurrentDate() {
    if (!bitRead(readbyte(regA), 7)) {
        byte m = readbyte(ADDR_CUR_MON);
        byte d = readbyte(ADDR_CUR_DAY);

        byte l1 = convertToCharAarray(m, month);
        byte l2 = convertToCharAarray(d, day);

        if (l1 == 1) {
            c2 = ' ';
            c1 = month[0];
        } else {
            c1 = month[1];
            c2 = month[0];
        }

        if (l2 == 1) {
            c4 = '0';
            c3 = day[0];
        } else {
            c3 = day[1];
            c4 = day[0];
        }
    }

    switch (btnMode2) {
        case DM_ADJ_NONE: //normal display mode, displays date
            disp(c2, false, c1, true, c4, false, c3, false);
            break;
        case DM_ADJ_MONTH: //if adjust month, flash the month digits
            if (secondIndLEDOn)
                disp(' ', false, ' ', true, c4, false, c3, false);
            else
                disp(c2, false, c1, true, c4, false, c3, false);
            break;
        case DM_ADJ_DAY: //if adjust day, flash the day digits
            if (secondIndLEDOn)
                disp(c2, false, c1, true, ' ', false, ' ', false);
            else
                disp(c2, false, c1, true, c4, false, c3, false);
            break;
        default:
            break;
    }

}

/** displays the current year (e.g. 2010) */
void dispCurrentYear() {
    if (!bitRead(readbyte(regA), 7)) {
        byte y = readbyte(ADDR_CUR_YEAR);

        byte l1 = convertToCharAarray(y, year);

        c2 = '2';
        c1 = '0';

        if (l1 == 1) {
            c4 = '0';
            c3 = year[0];
        } else {
            c3 = year[1];
            c4 = year[0];
        }
    }

    switch (btnMode2) {
        case DM_ADJ_NONE:
            disp(c2, false, c1, false, c4, false, c3, false);
            break;
        case DM_ADJ_YEAR:
            if (secondIndLEDOn)
                disp(c2, false, c1, false, ' ', false, ' ', false);
            else
                disp(c2, false, c1, false, c4, false, c3, false);
            break;
        default:
            break;
    }

}

/** displays the day of the week (e.g. day1 for Monday) */
void dispDayOfWeek() {
    if (!bitRead(readbyte(regA), 7)) {
        byte d = readbyte(ADDR_CUR_DOW);

        convertToCharAarray(d, dow);
    }

    switch (btnMode2) {
        case DM_ADJ_NONE: //normal display mode
            disp('d', false, 'A', false, 'y', false, dow[0], false);
            break;
        case DM_ADJ_DOW: //if adjust day of the week, flash the digit
            if (secondIndLEDOn)
                disp('d', false, 'A', false, 'y', false, ' ', false);
            else
                disp('d', false, 'A', false, 'y', false, dow[0], false);
            break;
    }
}

/** set the clock bus mode
/* INPUT or OUTPUT */
void setClkBusMode(int mode) {
    pinMode(ad0, mode);
    pinMode(ad1, mode);
    pinMode(ad2, mode);
    pinMode(ad3, mode);
    pinMode(ad4, mode);
    pinMode(ad5, mode);
    pinMode(ad6, mode);
    pinMode(ad7, mode);
}

/** read a byte from address */
byte readbyte(byte address) {
    byte readb = 0;

    //set address pins to output
    setClkBusMode(OUTPUT);
    //start READ cycle
    digitalWrite(rw, HIGH);
    //prepare to set address on bus
    digitalWrite(ds, HIGH);
    //delayMicroseconds(1);
    //set ALE high, on fall address latches
    digitalWrite(as, HIGH);

    //set address on bus
    digitalWrite(ad0, bitRead(address, 0));
    digitalWrite(ad1, bitRead(address, 1));
    digitalWrite(ad2, bitRead(address, 2));
    digitalWrite(ad3, bitRead(address, 3));
    digitalWrite(ad4, bitRead(address, 4));
    digitalWrite(ad5, bitRead(address, 5));
    digitalWrite(ad6, bitRead(address, 6));
    digitalWrite(ad7, bitRead(address, 7));

    //set ALE low, latch address
    digitalWrite(as, LOW);
    setClkBusMode(INPUT);
    //finish address setting
    digitalWrite(ds, LOW);
    //wait for data from address
    //set bus for input
    //start reading data
    readb = digitalRead(ad0) | (digitalRead(ad1) << 1) | (digitalRead(ad2) << 2) | (digitalRead(ad3) << 3) | (digitalRead(ad4) << 4) | (digitalRead(ad5) << 5) | (digitalRead(ad6) << 6) | (digitalRead(ad7) << 7);
    digitalWrite(ds, HIGH);

    return readb;
}

/** write a byte to address */
void writebyte(byte address, byte value) {
    //set address pins to output
    setClkBusMode(OUTPUT);
    //start READ cycle
    digitalWrite(rw, HIGH);
    //prepare to set address on bus
    digitalWrite(ds, HIGH);
    //set ALE high, on fall address latches
    digitalWrite(as, HIGH);
    //set address on bus
    digitalWrite(ad0, bitRead(address, 0));
    digitalWrite(ad1, bitRead(address, 1));
    digitalWrite(ad2, bitRead(address, 2));
    digitalWrite(ad3, bitRead(address, 3));
    digitalWrite(ad4, bitRead(address, 4));
    digitalWrite(ad5, bitRead(address, 5));
    digitalWrite(ad6, bitRead(address, 6));
    digitalWrite(ad7, bitRead(address, 7));
    digitalWrite(as, LOW);
    digitalWrite(rw, LOW);
    //set byte to write
    digitalWrite(ad0, bitRead(value, 0));
    digitalWrite(ad1, bitRead(value, 1));
    digitalWrite(ad2, bitRead(value, 2));
    digitalWrite(ad3, bitRead(value, 3));
    digitalWrite(ad4, bitRead(value, 4));
    digitalWrite(ad5, bitRead(value, 5));
    digitalWrite(ad6, bitRead(value, 6));
    digitalWrite(ad7, bitRead(value, 7));
    digitalWrite(rw, HIGH);
}

/** adjust a register value by 1*/
boolean adjust(byte address) {
    //read current value
    byte value = 0;
    byte b;
    if ((address < 0) || (address > 10)) return false;
    if (!bitRead(readbyte(regA), 7)) value = readbyte(address);
    b = readbyte(regB);
    //set SET bit of register B that will prevent double buffer update from internal buffer
    b = b | 0x80;
    writebyte(regB, b);

    if (bitRead(readbyte(regB), 7)) {
        switch (address) {
            case ADDR_CUR_SEC://seconds
                writebyte(address, 0); //reset
                break;
            case ADDR_ALM_SEC://seconds alarm
                writebyte(address, 0); //reset
                break;
            case ADDR_CUR_MIN://minutes
                if (value >= 59) {
                    writebyte(address, 0);
                } else {
                    value++;
                    writebyte(address, value);
                }
                break;
            case ADDR_ALM_MIN://minutes alarm
                if (value >= 59) {
                    writebyte(address, 0);
                } else {
                    value++;
                    writebyte(address, value);
                }
                break;
            case ADDR_CUR_HOUR://hours
                if (value >= 23) {
                    writebyte(address, 0);
                } else {
                    value++;
                    writebyte(address, value);
                }
                break;
            case ADDR_ALM_HOUR://hours alarm
                if (value >= 23) {
                    writebyte(address, 0);
                } else {
                    value++;
                    writebyte(address, value);
                }
                break;
            case ADDR_CUR_DOW://day of week
                if (value >= 7) {
                    writebyte(address, 1);
                } else {
                    value++;
                    writebyte(address, value);
                }
                break;
            case ADDR_CUR_DAY:
                if (value >= 31) {
                    writebyte(address, 1);
                } else {
                    value++;
                    writebyte(address, value);
                }
                break;
            case ADDR_CUR_MON://month
                if (value >= 12) {
                    writebyte(address, 1);
                } else {
                    value++;
                    writebyte(address, value);
                }
                break;
            case ADDR_CUR_YEAR://year
                if (value == 99) {
                    writebyte(address, 0);
                } else {
                    value++;
                    writebyte(address, value);
                }
                break;
        }
    }

    //mask regA and clear SET bit
    b = b & 0x7F;
    writebyte(regB, b);
    return true;
}

/** interrupt handler routine */
void intr() {
    interruptConter++;

    if (stopWatchStarted) {
        stopWatchCounter++;
    }

    switch (btnMode1) {
        case DM_TIME:
            switch (btnMode2) {
                case DM_ADJ_NONE:
                    dispCurrentTime();
                    break;
                case DM_ADJ_HOUR:
                    dispCurrentTime();
                    break;
                case DM_ADJ_MIN:
                    dispCurrentTime();
                    break;
                case DM_ADJ_MONTH:
                    dispCurrentDate();
                    break;
                case DM_ADJ_DAY:
                    dispCurrentDate();
                    break;
                case DM_ADJ_YEAR:
                    dispCurrentYear();
                    break;
                case DM_ADJ_DOW:
                    dispDayOfWeek();
                    break;
            }
            break;
        case DM_DATE:
            dispCurrentDate();
            break;
        case DM_YEAR:
            dispCurrentYear();
            break;
        case DM_DOW:
            dispDayOfWeek();
            break;
        case DM_STOP_WATCH:
            dispStopWatch();
            break;
        default:
            break;
    }

    //flashes the second indicator (the dot) every half second
    if (interruptConter > 63) {
        interruptConter = 0;
        secondIndLEDOn = !secondIndLEDOn;
    }
}

/*********************
 * Arduino routines
 *********************/
void setup() {
    init7seg();
    pinMode(btnPin1, INPUT);
    pinMode(btnPin2, INPUT);
    digitalWrite(btnPin1, HIGH);
    digitalWrite(btnPin2, HIGH);

    pinMode(as, OUTPUT);
    pinMode(ds, OUTPUT);
    pinMode(rw, OUTPUT);

    //delay after power up to start-up
    digitalWrite(as, LOW);
    digitalWrite(ds, LOW);
    digitalWrite(rw, LOW);
    delayMicroseconds(200);

    // RS3 RS2 RS1 RS0 = 1001 set SQW output frequency to 128 Hz
    byte a = 41;
    writebyte(regA, a);

    byte b = readbyte(regB);
    b = b | 0xF;
    writebyte(regB, b);

    attachInterrupt(0, intr, RISING);
    c1 = ' ';
    c2 = ' ';
    c3 = ' ';
    c4 = ' ';
}

void loop() {
    if (digitalRead(btnPin1) == LOW && !btn1Pressed) {//debouncing btn1
        delayMilliseconds(20);
        if (digitalRead(btnPin1) == LOW) {
            switch (btnMode2) {
                case DM_ADJ_NONE:
                    btnMode1 = (btnMode1 + 1) % 5;
                    break;
                case DM_ADJ_HOUR:
                    adjust(ADDR_CUR_HOUR);
                    break;
                case DM_ADJ_MIN:
                    adjust(ADDR_CUR_MIN);
                    break;
                case DM_ADJ_MONTH:
                    adjust(ADDR_CUR_MON);
                    break;
                case DM_ADJ_DAY:
                    adjust(ADDR_CUR_DAY);
                    break;
                case DM_ADJ_YEAR:
                    adjust(ADDR_CUR_YEAR);
                    break;
                case DM_ADJ_DOW:
                    adjust(ADDR_CUR_DOW);
                    break;
                default:
                    break;
            }

            btn1Pressed = true;
        }
    }

    if (digitalRead(btnPin1) == HIGH) {
        delayMilliseconds(20);

        if (digitalRead(btnPin1) == HIGH) {
            btn1Pressed = false;
        }
    }

    if (digitalRead(btnPin2) == LOW && !btn2Pressed) {
        delayMilliseconds(20);

        if (digitalRead(btnPin2) == LOW) {//debouncing btn2
            if (btnMode1 == DM_TIME) {
                btnMode2 = (btnMode2 + 1) % 7;
            }

            if (btnMode1 == DM_STOP_WATCH && !stopWatchStarted && stopWatchInit) {
                stopWatchInit = false;
                stopWatchStarted = true;
            } else if (btnMode1 == DM_STOP_WATCH && stopWatchStarted && !stopWatchInit) {
                stopWatchStarted = false;
            } else if (btnMode1 == DM_STOP_WATCH && !stopWatchStarted && !stopWatchInit) {
                stopWatchInit = true;
                stopWatchCounter = 0;
            }

            btn2Pressed = true;
        }
    }

    if (digitalRead(btnPin2) == HIGH) {//debouncing btn2
        delayMilliseconds(20);
        if (digitalRead(btnPin2) == HIGH) {
            btn2Pressed = false;
        }
    }
}

Despite its convenience, the Arduino IDE lacks some key features most modern IDEs have. To name a few, the Arduino IDE does not yet support auto-completion, code folding and contextual help. And the integrated parser sometimes have difficulties parsing complex code structures and do not give adequate information for the errors encountered. While it does not matter much for writing simple programs, the drawbacks are obvious when developing more complex applications. Since I am a software developer, I personally prefer a more advanced IDE.

If you are using Eclipse, then there is already a plugin available for AVR development, though I have not personally tried it I have seen other people using it regularly. Looking at the Arduino playground instructions for this plugin, it seems that it is pretty straight forward to set up. But if you are using NetBeans, currently there’s no Arduino support yet.

Luckily, it is actually fairly straight forward to add Arduino support in the NetBeans environment. In this article, I will show you step by step instructions on how to prepare your NetBeans environment for Arduino development purpose.

For those who are impatient and know your way around the NetBeans environment, you can download and install ArduinoPlugin_v1.0.tar.gz (Tools -> Plug-ins, under Downloaded tab, choose add plug-ins) and get started right away. You do need to configure your NetBeans environment to support avr-gcc tool chain before you can start using the Arduino module. If you are unsure how to do this, please read on.

Prerequisite

This plugin requires a functional Arduino development environment. Since this plug-in relies on the Arduino core libraries for code compilation, Arduino must be installed first. You can refer to the Getting Started with Arduino guide on the official Arduino site on how to install the Arduino programming environment.

The instructions in this article assumes that you are running Arduino under Linux, but I think you can adapt it to Windows environment with relatively few changes. Here is a list of the software versions I have installed on my PC.

Ubuntu 10.04 (64bit)
avr-gcc 4.3.4
avrdude 5.10
RXTX-2.2pre2
NetBeans 6.8
arduino-0018

Depending on your particular settings (e.g. the installation path of arduino-0018 is not located under your home directory or it is installed under a different directory name), minor modifications to the template might be needed.

Configure AVR Tool Chain

To setup the NetBeans environment, we need to first setup the AVR tool chain. To do so, first launch NetBeans, navigate to Tools -> Options and click “Add” under C/C++/Build Tools (see screen shot below), and from there we can create a new tool chain called Arduino and configure the paths in the right-hand-side pane accordingly. Here is a screenshot of the tool chain configuration on my system:

Base Directory: /usr/bin
C Compiler: /usr/bin/avr-gcc
C++ Compiler: /usr/bin/avr-g++
Assembler: /usr/bin/avr-as
Debugger: /usr/bin/gdb (this is not important since we do not run Arduino applications within NetBeans anyway)

avr-gcc tool chain setup in NetBeans

In order for the auto-complete feature to work with the Arduino/AVR header files, we also need to setup the paths under the Code Assistance tab. To begin with, you would need to setup the following paths:

~/arduino-0018/hardware/arduino/cores/arduino (assuming that you installed Arduino 0018 under your home directory)
~/arduion-0018/libraries/
/usr/lib/gcc/avr/4.3.4/include

If you use libraries located in other locations, you will need to add those paths to the C/C++ compiler code assistance tab as well.

Install the Arduino Plugin

To install the plugin, download the NetBeans module first (ArduinoPlugin_v1.0.tar.gz). Use the following command to extract the NetBeans Module (ArduinoPlugin_v1.0.nbm):

tar zxf ArduinoPlugin_v1.0.tar.gz

Then go to Tools -> Plugins, under Downloaded tab, choose Add plugins. Navigate to where you saved the .nbm file and click OK.

After installing the plugin, the plugin option screen should look like the following:

Arduino Plugin installed

How to use

To create an Arduino project, go to project new and choose Arduino project template.

Create an Arduino Project

After the project is created, you should see two files (main.pde and makefile) under Source Files folder, and main.pde contains the code skeleton:

#define __AVR_ATmega328P__

#include <binary.h>
#include <HardwareSerial.h>
#include <pins_arduino.h>
#include <WConstants.h>
#include <wiring.h>
#include <wiring_private.h>
#include <WProgram.h>
#include <EEPROM/EEPROM.h>

void setup()
{

}

void loop()
{

}

I tried to make the code structure look as close to that in Arduino IDE as possible, but for the code auto completion to work, some extra includes are needed. Also, note that I have included the MCU definition (#define __AVR_ATmega328P__) to get the the MCU specific intellisense work. You can change this to the type of MCU you are targeting.

Auto Completion

To build your project, right click on the makefile and choose make or make clean. If your build is successful, you should see a HEX file built in the applet directory within your project root. And you can use the Make Target -> upload option to upload the HEX file onto the Arduino board.

Build and Upload

Behind the scene

The Arduino plugin for NetBeans is developed as a NetBeans project sample module. The makefile is adapted from the make file used within the Arduino environment and is discussed here.

I had put some additional comments in places where you might need to edit for it to work with your projects. For instance, your project may link to more modules than the ones listed below.

#Note that if your program has dependencies other than those
#already listed below, you will need to add them accordingly.
C_MODULES = \
$(ARDUINO)/wiring_pulse.c \
$(ARDUINO)/wiring_analog.c \
$(ARDUINO)/pins_arduino.c \
$(ARDUINO)/wiring.c \
$(ARDUINO)/wiring_digital.c \
$(ARDUINO)/WInterrupts.c \
$(ARDUINO)/wiring_shift.c \

CXX_MODULES = \
$(ARDUINO)/Tone.cpp \
$(ARDUINO)/main.cpp \
$(ARDUINO)/WMath.cpp \
$(ARDUINO)/Print.cpp \
$(ARDUINO)/HardwareSerial.cpp \
$(ARDUINO_LIB)/EEPROM/EEPROM.cpp \

Also, I followed the technique used in the Arduino IDE to assemble the sketch with other necessary information and the main program at compile time (see the portion of the makefile below) to keep main.pde as simple as possible. The only issue is that compilation errors are referenced against the assembled source code rather than the code you write in main.pde. I had originally thought about putting all the necessary code in main.pde and thus would not require code merge at compile time, but it would make the code less compatible with the Arduino IDE environment.

#applet_files: main.pde
applet/$(TARGET).cpp: main.pde
# Here is the “preprocessing”.
# It creates a .cpp file based with the same name as the .pde file.
# On top of the new .cpp file comes the WProgram.h header.
# and prototypes for setup() and Loop()
# Then the .cpp file will be compiled. Errors during compile will
# refer to this new, automatically generated, file.
# Not the original .pde file you actually edit…
test -d applet || mkdir applet
echo ‘#include “WProgram.h”‘ > applet/$(TARGET).cpp
echo ‘void setup();’ >> applet/$(TARGET).cpp
echo ‘void loop();’ >> applet/$(TARGET).cpp
cat main.pde >> applet/$(TARGET).cpp

Future Enhancement

Currently, there is no serial port monitor integrated with the NetBeans environment. So if your code uses the Serial class (i.e. Serial.println()), you will have to use the serial monitor bundled with Arduino. This should not be a big issue though, since even in Arduino, you have to click on the Serial Monitor every time after you upload the code to use it any way. I am planning on integrating the serial monitor with NetBeans in the future but it would probably take some time.

Download

Arduino plugin for NetBeans: ArduinoPlugin_v1.0.tar.gz

The following code listing illustrates how to obtain temperature readings from LM19 with an Arduino. The code assumed that the sensor output is connected to Analog 0 pin.

void setup()
{
    Serial.begin(9600);
}

void loop()
{
  float vin = 5.0 * analogRead(0) / 1024.0;
  Serial.print(vin);
  Serial.print("  ");
  float tempC = (1.8663 - vin) / 0.01169;
  float tempF = 1.8 * tempC + 32.0;
  Serial.print(tempC);
  Serial.print("  ");
  Serial.println(tempF);
  delay(100);
}

In the code above, I used the approximated linear transfer function shown below. It is fairly accurate when the temperature range is around room temperature.
\[T_{Celcius} = \frac{(1.8663-V_o}{0.01169}\]

For more accurate temperature measurement over the full operating range, the following equation can be used:
\[T_{Celcius} = \sqrt{2.1962 \times 10^6 + \frac {1.8639 - V_o}{3.88 \times 10^{-6}}} - 1481.96\]

What makes LTC1665/LTC1660 attractive is that the D/A converters addressable via the serial interface. And thus, controlling the eight D/A channels requires relatively few connections with ATmega328p.

The schematic below illustrates how to utilize a D/A channel with input from ATmega328p. Pin IN, SCK, CSLD, CLR can be connected to any pins that accept digital input. And the pin labeled Analog Out outputs the conversion result.

LTC1665CN

The output voltage from the function output() is determined by:
\[Vout = \frac{Vref \times val}{256}\]
for LTC1665 (8 bit), and
\[Vout = \frac{Vref \times val}{1024}\]
for LTC1660 (10 bit). In my example above, Vref is connected to Vcc and is typically around 5V.

The following code uses Arduino to drive the DAC clock. To test the conversion result, the analog output is connected with an Arduino analog input pin.

const int pinIN = 8;
const int pinSCK = 7;
const int pinCSLD= 3;
const int pinCLR =12;

const int pinAnalogOut = 5;

void setup()
{
  pinInit();
  Serial.begin(9600);
  output(1, 64);
  Serial.println(analogRead(pinAnalogOut));
}

void pinInit()
{
  pinMode(pinIN, OUTPUT);
  pinMode(pinSCK, OUTPUT);
  pinMode(pinCSLD, OUTPUT);
  pinMode(pinCLR, OUTPUT);

  digitalWrite(pinCLR, HIGH);
  digitalWrite(pinSCK, LOW);
  digitalWrite(pinCSLD, HIGH);
}

//Performs D/A conversion
void output(long chn, long val)
{
  //the control word is 16 bits
  //the high 4 bits defines the output channel
  long t = chn << 12;

  //the lower 4 bits are don't cares so we make
  //them zeros.
  t = t | val << 4;
  //for LTC1660 it has 10bit resolution this line will
  //need to change to:
  //t = t | val << 2;

  digitalWrite(pinCSLD, LOW);
  for (long i = 15; i >= 0; i--)
  {
    long b = (t >> i) & 1;
    digitalWrite(pinIN, b);
    digitalWrite(pinSCK, HIGH);
    digitalWrite(pinSCK, LOW);
  }

  digitalWrite(pinCSLD, HIGH);
}

void loop()
{
}

The bit resolution difference between LTC1665 and LTC1660 is handled by the code within the output() function.

Before I start, I should mention that according to the product documentation, the normal operation voltage (Vdd) for LIS3LV02DL is between 2.16V and 3.6V. Ideally you should interface LIS3LV02DL with CMOS logic level rather than the standard TTL logic level Arduino provides. In order for the accelerometer to operate within spec, you should lower the Arduino supply voltage to 3.3V and will most likely have to reduce the crystal frequency to 8-12MHz to accommodate the reduced voltage.

That said, the absolute maximum supply voltage (Vdd) for LIS3LV02DL is 6V. So it should be able to withstand the 5V Arduino operates on. I was able to power LIS3LV02DL using Arduino’s power source without experiencing any issues. But, it is definitely not recommended for prolonged use since according to the product documentation:

“exposure to maximum rating conditions for extended periods may affect device reliability.”

I used the method I mentioned previously to mount the chip onto a perf board and soldered on connector pins to make it easier for testing on a breadboard.

My setup is like this:

LIS3LV02DL Accelerometer with Arduino

With LIS3LV02DL pin 3 connected to Arduino digital pin 11, LIS3LV02DL pin 2 connected to Arduino digital pin 12, pin 5 connected to digital pin 13 and pin 6 connected to digital pin 10.

The following is the code to retrieve data from the accelerometer using SPI.

#define DATAOUT 11//MOSI lis3lv02dl pin3
#define DATAIN  12//MISO lis3lv02dl pin2
#define SPICLOCK  13//sck lis3lv02dl pin5
#define CS 10//ss lis3lv02dl pin6, active low

//register addresses
const int REG_WHO_AM_I = 0x0f; //3A
const int REG_OFFSET_X = 0x16;
const int REG_OFFSET_Y = 0x17;
const int REG_OFFSET_Z = 0x18;
const int REG_GAIN_X = 0x19;
const int REG_GAIN_Y = 0x1A;
const int REG_GAIN_Z = 0x1B;
const int REG_CTRL_REG1 = 0x20;
const int REG_CTRL_REG2 = 0x21;
const int REG_CTRL_REG3 = 0x22;
const int REG_HP_FILTER_RESET = 0x23;
const int REG_STATUS_REG = 0x27;
const int REG_OUTX_L = 0x28;
const int REG_OUTX_H = 0x29;
const int REG_OUTY_L = 0x2a;
const int REG_OUTY_H = 0x2b;
const int REG_OUTZ_L = 0x2c;
const int REG_OUTZ_H = 0x2d;
const int REG_FF_WU_CFG = 0x30;
const int REG_FF_WU_SRC = 0x31;
const int REG_FF_WU_ACK = 0x32;
const int REG_FF_WU_THS_L = 0x34;
const int REG_FF_WU_THS_H = 0x35;
const int REG_FF_WU_DURATION = 0x36;
const int REG_DD_CFG = 0x38;
const int REG_DD_SRC = 0x39;
const int REG_DD_ACK = 0x3a;
const int REG_DD_THSI_L = 0x3c;
const int REG_DD_THSI_H = 0x3d;
const int REG_DD_THSE_L = 0x3e;
const int REG_DD_THSE_H = 0x3f;

//axis definitions
const int AXIS_X = 1;
const int AXIS_Y = 2;
const int AXIS_Z = 3;

const int CTRL_REG2_FS = 7;

void setup()
{
  byte b = 0;

  Serial.begin(9600);

  pinSetup();
  initSys();
  b = readRegister(REG_WHO_AM_I);
  Serial.println(b, HEX); //should be 3A

  setScale(1); //set range to 6g
}

void loop()
{
  Serial.print(" x = ");
  Serial.print(getValue(AXIS_X));
  Serial.print(" y = ");
  Serial.print(getValue(AXIS_Y));
  Serial.print(" z = ");
  Serial.println(getValue(AXIS_Z));
}

//transfer a byte using SPI
byte spiTransfer(volatile byte data)
{
  SPDR = data;

  while (!(SPSR & _BV(SPIF)));

  return SPDR;
}

void initSys()
{
  //disable device
  digitalWrite(CS,HIGH); 

  //initialize SPI
  SPCR = _BV(SPE) | _BV(MSTR)| _BV(CPOL)| _BV(CPHA);    

  //enable all axes
  writeRegister(REG_CTRL_REG1, 0x87);
}

void pinSetup()
{
  pinMode(DATAOUT, OUTPUT);
  pinMode(DATAIN, INPUT);
  pinMode(SPICLOCK,OUTPUT);
  pinMode(CS,OUTPUT);
}

byte getGain(int axis)
{
  byte r = 0;

  switch (axis)
  {
    case AXIS_X:
      r = readRegister(REG_GAIN_X);
    break;
    case AXIS_Y:
      r = readRegister(REG_GAIN_Y);
    break;
    case AXIS_Z:
      r = readRegister(REG_GAIN_Z);
    break;
    default:
      r = 0xff;
    break;
  }

  return r;
}

byte getOffset(int axis)
{
  byte r = 0;

  switch (axis)
  {
    case AXIS_X:
      r = readRegister(REG_OFFSET_X);
    break;
    case AXIS_Y:
      r = readRegister(REG_OFFSET_Y);
    break;
    case AXIS_Z:
      r = readRegister(REG_OFFSET_Z);
    break;
    default:
      r = 0xff;
    break;
  }

  return r;
}

void setScale(byte s)
{
  byte r = readRegister(REG_CTRL_REG2);

  if (s == 0) { // 2g
    r &= ~_BV(CTRL_REG2_FS);
  } else { //6g
    r |= _BV(CTRL_REG2_FS);
  }

 writeRegister(REG_CTRL_REG2, r);
}

int getValue(int axis)
{
  int r = 0;
  byte h, l;

  switch (axis)
  {
    case AXIS_X:
      l = readRegister(REG_OUTX_L);
      h = readRegister(REG_OUTX_H);
    break;
    case AXIS_Y:
      l = readRegister(REG_OUTY_L);
      h = readRegister(REG_OUTY_H);
    break;
    case AXIS_Z:
      l = readRegister(REG_OUTZ_L);
      h = readRegister(REG_OUTZ_H);
    break;
    default:
      l = 0;
      h = 0;
    break;
  }

  r = h << 8 | l;

  return r;
}

byte readRegister(byte reg)
{
   digitalWrite(CS, LOW);
   spiTransfer(reg | 0x80);
   byte b = spiTransfer(0);
   digitalWrite(CS, HIGH); 

   return b;
}

void writeRegister(byte reg, byte data)
{
   digitalWrite(CS, LOW);
   spiTransfer(reg & 0x7F);
   spiTransfer(data);
   digitalWrite(CS, HIGH);
}

In the global constants area, I listed all the registers available to LIS3LV02DL. It is relatively straight-forward to use them and you can consult the product documentation for more information. The readRegister/writeRegister are the two main functions to read from and write to the registers defined earlier. getValue returns the accelerometer reading of the axis specified. setScale sets the scale to either 2G or 6G, etc.

Without further due, here’s the schematics of the 4 digit 7 segment display (click for higher resolution pictures):

4 Digit 7 Segment Display

For finer controls, I left the MR OE pins (pin 10 and 13) unconnected so that they can be controlled by program. But for general use, you can connect pin 10 (MR) to Vcc and pin 13 (OE) to ground so that the output is always enabled.

Here’s the finished display (the letters displayed are “A.S.A.P”)

The display in action (showing A.S.A.P.)

It is fairly straight forward to write programs to interact with the above 4 digit display. The following C code offers a simple method disp() to display letters/digits that are predefined (see the comment section before the code and you will get an idea how to build your own symbols other than the ones included). The four boolean variables (dot1 to dot4) are used to turn on the decimal point on each segment independent of what is being displayed.

//aaaaaa
//f    b
//fggggb
//e    c
//eddddc p

//   abcdefgp ~abcdefgp DEC	~DEC
//1  00001100  11110011 12 	243
//2  11011010  00100101 218 101
//3  11110010  00001101 242 13
//4  01100110  10011001 102	153
//5  10110110  01001001 182	73
//6  10111110  01000001 190	65
//7  11100000  00011111 224	31
//8  11111110  00000001 254	1
//9  11110110  00001001 246	9
//0  11111101  00000010 253	2
//A  11101110  00010001 238	17
//b  00111110  11000001 62	193
//c  00011010  11100101 26	229
//C  10011100  01100011 156	99
//d  01111010  10000101 122 133
//e  11011110  00100001 222 33
//E  10011110  01100001 158 97
//F  10001110  01110001 142	113
//g  11110110  00001001 246	9
//H  01101110  10010001 110	145
//h  00101110  11010001 46	209
//I  01100000  10011111 96 	159
//J  01111000  10000111 120	135
//L  00011100  11100011 28 	227
//n  00101010  11010101 42	213
//o  00111010  11000101 58	197
//P  11001110  00110001 206	49
//q  11100110  00011001 230	25
//r  00001010  11110101 10	245
//S  10110110  01001001 182 73
//t  00011110  11100001 30	225
//u  00111000  11000111 56	199
//U  01111100  10000011 124	131
//y  01110110  10001001 118	137
//-  00000010  11111101 2 	253
//-  10000000  01111111 128	127
//-  00010000  11101111 16	239
//.  00000001  11111110 1 	254
//|| 01101100  10010011 108	147
//=  10010000  01101111 144 111
//=  10000010  01111101 130 125
//=  00010010  11101101 18	237
//=- 10010010  01101101 146 109

int latchPin = 10;
int clockPin = 7;
int dataPin = 3;

//note that for common cathode displays the
//bit values are inverted (see code)
const int COMMON_ANODE = 1; //1 CA, 0 CC

struct CharMap
{
  char c;
  byte v;
};

const int cmap_len = 41;
struct CharMap cmap[] = {
{' ', 0},
{'1', 12},
{'2', 218},
{'3', 242},
{'4', 102},
{'5', 182},
{'6', 190},
{'7', 224},
{'8', 254},
{'9', 246},
{'0', 253},
{'A', 238},
{'b', 62},
{'c', 26},
{'C', 156},
{'d', 122},
{'e', 222},
{'E', 158},
{'F', 142},
{'g', 246},
{'H', 110},
{'h', 46},
{'I', 96},
{'J', 120},
{'L', 28},
{'n', 42},
{'o', 58},
{'P', 206},
{'q', 230},
{'r', 10},
{'S', 182},
{'t', 30},
{'u', 56},
{'U', 124},
{'y', 118},
{'-', 2},
{'~', 128},
{'_', 16},
{'.', 1},
{'|', 108},
{'=', 144}
};

byte getCode(char c)
{
  byte r = 2;

  for (int i = 0 ; i < cmap_len ; i++) {
    if (c == cmap[i].c) {
      r = cmap[i].v;
      break;
    }
  }

  return r;
}

//display c1 c2 c3 c4
//Note the boolean values for dot1 dot2 dot3 and dot4
//indicates whether or not to show the decimal point
void disp(char c1, bool dot1, char c2, bool dot2, char c3, bool dot3, char c4, bool dot4)
{
  byte b1 = getCode(c1);
  byte b2 = getCode(c2);
  byte b3 = getCode(c3);
  byte b4 = getCode(c4);

  if (dot1 == true) b1 += 1;
  if (dot2 == true) b2 += 1;
  if (dot3 == true) b3 += 1;
  if (dot4 == true) b4 += 1;

  if (COMMON_ANODE == 1) {
    b1 = 255 - b1;
    b2 = 255 - b2;
    b3 = 255 - b3;
    b4 = 255 - b4;
  } 

  digitalWrite(latchPin, LOW);        

  shiftOut(dataPin, clockPin,  b4);
  shiftOut(dataPin, clockPin,  b3);
  shiftOut(dataPin, clockPin,  b2);
  shiftOut(dataPin, clockPin,  b1);

  digitalWrite(latchPin, HIGH);
}

void setup7seg()
{
  pinMode(latchPin, OUTPUT);
  pinMode(clockPin, OUTPUT);
  pinMode(dataPin, OUTPUT);

  disp(' ', false, ' ', false, ' ', false, ' ', false);
}

void shiftOut(uint8_t dataPin, uint8_t clockPin, byte val)
{
	int i;

	for (i = 0; i < 8; i++)  {
		digitalWrite(dataPin, (val & _BV(i)));
                delayMicroseconds(10);
		digitalWrite(clockPin, HIGH);
                delayMicroseconds(10);
		digitalWrite(clockPin, LOW);
                delayMicroseconds(10);
	}
}

void setup()
{
  setup7seg();
}

void loop()
{
  disp('d',false,'I',false,'S',false,'C',false); //displays the word dISC
  delay(1000);
}

The shiftOut method is actually included in standard Arduino libraries, the reason I included it in my code is that I had to add slight delay between each digitalWrite otherwise the output is not always correct. I suspect this is due to the long wiring I used on the circuit board.

The standard way of connecting a unipolar stepper motor to the parallel port is to use a Darlington driver such as ULN2003 and there are already many examples out there on how to do this. In this post, I will show you how to build a simple stepper motor driver using discrete MOSFETs.

In the circuit diagram below, you will find that the four power MOSFETs are used as switches for each coil in the stepper motor (the stepper motor I used in this example is a MITSUMI M35SP-9. In theory, any uni-polar stepper motors should work with this circuit). A pull-down resistor is attached to the gate of each MOSFET. This is important as otherwise the interference from the port would prevent the MOSFET from switching reliably.

Controller Circuit

The benefit of using discrete MOSFET is that they can handle extremely high current loads. Using IRFZ22, the coil current can be as high as 10 Amp.

Stepper Motor Controller

The following C code sets the data port (pin 2, 3, 4, 5) to high in order so that the stepper motor would rotate clockwise. If you want the motor to rotate counter-clockwise, simply change the output order to 8,4,2,1.

#include <sys/io.h>

#define PAR_PORT 0x378 

void main()
{
	while (1)
	{
		outb(1, PAR_PORT);
		outb(2, PAR_PORT);
		outb(4, PAR_PORT);
		outb(8, PAR_PORT);
	}
}                                            

#include <stdio.h>
#include <stdlib.h>
#include <limits.h>
#include <math.h>
#include <iostream>

using namespace std;

bool IsPrime(unsigned long long n) {
	bool r = true;

	for (unsigned long long i = 3; i < sqrt((double) n) + 1; i+= 2)
	{
		if (n % i ==0) {
			r = false;
			break;
		}
	}

	return r;
}

bool IsPalindrome(unsigned long long n) {
	bool r = true;
	char s[30];
	int l = sprintf(s, "%llu", n);

	if (l == 1 && n != 1) {
		r = true;
	} else	{
		for (int i = 0; i < l/2; i++) {
			if (s[i] != s[l-i-1]) {
				r = false;
				break;
			}
		}
	}

	return r;
}

/*
 * usage: palprime [lbound] [ubound]
 */
int main(int argc, char** argv) {
	unsigned long long beginNum = 3;
	unsigned long long endNum = 3;

	if (argc == 2) { // lbound default to 3
#ifdef _WIN32
		endNum = _strtoui64(argv[1], NULL, 10);
#else
		endNum = strtoull(argv[1], NULL, 10);
#endif

	} else if (argc == 3) {
#ifdef _WIN32
		beginNum = _strtoui64(argv[1], NULL, 10);
		endNum = _strtoui64(argv[2], NULL, 10);
#else
		beginNum = strtoull(argv[1], NULL, 10);
		endNum = strtoull(argv[2], NULL, 10);
#endif
	}

        unsigned long long i = beginNum;

        while (i < endNum) {
                char s[30];
                int l = sprintf(s, "%llu", i);

		//length cannot be even as even length palindrome numbers
		//can be divided by 11.
                if (l % 2 == 0) {
                    i = ((unsigned long long) (i / 10)) * 100 + 1;
                    continue;
                }

		if (IsPalindrome(i)) {
			if (IsPrime(i)) {
				cout << i << endl;
			}
		}

                i+=2;

                if (s[0] % 2 == 0) {
                    i+=pow(10, l-1);

		    //leading/ending number cannot be 5
                    if (((int) (s[0] - '0')) + 1 == 5) {
                        i += 2 * pow(10, l-1);
                    }
                }
	}
	return (EXIT_SUCCESS);
}

At first, I was trying to find all the palprimes that can be represented by 64 bit integers. But soon I realized that it would take months to do so using the code above with a quad-core PC (using 4 processes with different ranges). Anyway, here’s the last few palindromic primes less than 10,000,000,000,000:

9999899989999
9999901099999
9999907099999
9999913199999
9999919199999
9999938399999
9999961699999
9999970799999
9999980899999
9999987899999

And here are a few interesting ones:

11357975311
1112345432111
1300000000031
1700000000071
1900000000091
7900000000097
9200000000029
1357900097531

Results

When presented with images that are clear, the algorithm correctly identified most of them (see images below):

Building (Microsoft Research Digital Image)

Street (Microsoft Research Digital Image)

Sky

Flower

The following images illustrate how the original image (top right) is divided into sub regions. Canny detection is performed on each of the sub images.

When performing Hough Transform, I chose to detect up to ten lines in each image, with the following stepping parameter (the detection results are very sensitive to these parameters, the following parameters were chosen based on experiment results):
\[\rho=1, \theta=0.01\]

Out of all the detected lines, a few sections are selected based on line continuity and the calculated average gradients around the detected lines. The following images shows the chosen Hough line segments based on the algorithm.

The table below shows the gradient index calculated within each area (the average of the gradients along all the chosen line segments within a sub-image. The result is scaled by 1000, the scale factor is chosen such that for clear images the resulted index is greater than 1 and for blur images the resulted index is less than 1).

And the sub images are indexed as follows:

The algorithm can also detect images with deliberate blur regions (e.g. Bokeh). The results are illustrated below:

Plant (Microsoft Research Digital Image)

Note that the 0′s in the detection results indicate that within those regions, no lines could be reliably detected and thus those regions are considered blurred.
Generally speaking, when an image contains both blurred and clear regions, some of the indexes will be zero and others will be greater than one.

The following images are detected as blurred, with the detected indexes far less than one.

Boat (Microsoft Research Digital Image)

Candle

Limitations

when image contrast is low, or when objects borders are not clearly defined, the algorithm may have difficulty in distinguishing whether an image is blurred. Take the following two cloud images for instance, the image on the left was correctly classified as a clear image due to the relatively high contrast around the center. But the image to the right was classified as blurred due to its lack of contrast.

Cloud

Cloud

Update (7/12/2010)

A few readers requested the code for calculating gradients. The method I used was quite simple, please see the LineUtils code below:

/*
 * File:   lineutils.cpp
 * Author: kwong
 *
 * Created on June 5, 2009, 8:47 PM
 */

#include "LineUtils.h"

#include <math.h>
#include <stdlib.h>
#include <iostream>
#include <ios>

using namespace std;

namespace KDW {
    const float PI = 3.14159265358979;
    const float Epsilon = 1e-5;
    const float MaxGradient = 1e6;

    LineUtils::LineUtils() {
    }

    LineUtils::LineUtils(const LineUtils& orig) {
    }

    LineUtils::~LineUtils() {
    }

    /**
     * Get the equation parameters for the line that passes through (x,y) and is perpendicular
     * to the line specified by parameters (p0, theta0) in normal form.
     *
     * @param p0 : distance to line from origin.
     * @param theta0 : the slope of p0.
     * @param x : x coordinate of the point where the perpendicular line passes through
     * @param y : y coordinate of the point where the perpendicular line passes through
     * @param &p : the perpendicular line's distance from origin.
     * @param &theta : the slope of p.
     **/
    void LineUtils::GetPerpendicularLineParameters(float p0, float theta0, float x, float y, float &p, float &theta) {
        float x0 = p0 * cos(theta0);
        float y0 = p0 * sin(theta0);

        p = sqrt((x0 - x)*(x0 - x) + (y0 - y)*(y0 - y));

        float a1 = theta0 - PI / 2.0;
        float a2 = theta0 + PI / 2.0;

        //d=|x0 * cos a + y0 * sin a - p|
        float d1 = abs(x * cos(a1) + y * sin(a1) - p);
        float d2 = abs(x * cos(a2) + y * sin(a2) - p);

        if (d1 < d2)
            theta = a1;
        else
            theta = a2;
    }

    /**
     * Get a line segement's coordinates. The segement is centered at x0, y0.
     *
     * @param p : distance to line from origin.
     * @param theta : the slope of p.
     * @param x0 : x coordinate of the segement center.
     * @param y0 : y coordinate of the segement center.
     * @param numOfPoints : the number of coordinate points to collect at either side
     *                      of (x0, y0)
     * @param points[] : returns the x,y coordinates of the points on the line segement in IppiPoint.
     **/
    void LineUtils::GetLineIntervalPoints(float p, float theta, float x0, float y0, int numOfPoints, IppiPoint points[]) {
        if (abs(sin(theta)) < Epsilon) {
            for (int xp = x0 - numOfPoints; xp <= x0 + numOfPoints; xp++) {
                points[(int) (xp + numOfPoints - x0)].x = xp;
                points[(int) (xp + numOfPoints - x0)].y = y0;
            }
        } else if (abs(cos(theta)) < Epsilon) {
            for (int yp = y0 - numOfPoints; yp <= y0 + numOfPoints; yp++) {
                points[(int) (yp + numOfPoints - y0)].y = yp;
                points[(int) (yp + numOfPoints - y0)].x = x0;
            }
        } else if ((abs(theta) > 0 && abs(theta) <= 0.25 * PI) ||
                (abs(theta) > 0.75 * PI && abs(theta) <= PI) ||
                (theta > PI && theta <= 1.25 * PI) ||
                (theta > 1.75 * PI and theta <= 2.0 * PI)) {
            for (int xp = x0 - numOfPoints; xp <= x0 + numOfPoints; xp++) {
                points[(int) (xp + numOfPoints - x0)].x = xp;
                points[(int) (xp + numOfPoints - x0)].y = (int) ((p - points[(int) (xp + numOfPoints - x0)].x * cos(theta)) / sin(theta));
            }
        } else {
            for (int yp = y0 - numOfPoints; yp <= y0 + numOfPoints; yp++) {
                points[(int) (yp + numOfPoints - y0)].y = yp;
                points[(int) (yp + numOfPoints - y0)].x = (p - points[(int) (yp + numOfPoints - y0)].y * sin(theta)) / cos(theta);
            }
        }
    }

    /**
     * Get a line segement's coordinates. The segement is centered at x0, y0.
     *
     * @param points[] : the x,y coordinate of the input points (ordered).
     * @param threashold : the threashold of disconnected points before a line is considered no
     *              longer connected.
     * @param lpoints[] : the x,y coordinates of the points in the detected longest connected line.
     * @param &maxLen : the maximum length of the output array, addtional line points
     *                  will be discarded if exceed this limit.
     **/
    void LineUtils::GetLongestConnectedLinePoints(IppiPoint points[], int len, int threshold, IppiPoint lpoints[], int &maxLen) {
        int maxIndexEnd = 0, curRunLength = 0, maxRunLength = 0;

        lpoints[curRunLength] = points[0];

        for (int i = 1; i < len; i++) {
            //if ((abs(points[i].x - points[i - 1].x) > threshold) || (abs(points[i].y - points[i - 1].y) > threshold)) {
            if ((abs(points[i].x - lpoints[curRunLength].x) > threshold) || (abs(points[i].y - lpoints[curRunLength].y) > threshold)) {
                //if (curRunLength > maxRunLength) {
                if (curRunLength > maxRunLength) {
                    maxRunLength = curRunLength;
                    maxIndexEnd = i;
                }
                curRunLength = 0;
                lpoints[curRunLength] = points[i];

                //}
            } else {
                if (curRunLength >= maxLen) {
                    maxRunLength = maxLen;
                    break;
                }

                curRunLength++;
                lpoints[curRunLength] = points[i];
            }
        }

        for (int i = maxIndexEnd - maxRunLength - 1; i < maxIndexEnd; i++) {
            if (i - (maxIndexEnd - maxRunLength) - 1 < maxRunLength) {
                lpoints[i - (maxIndexEnd - maxRunLength - 1)] = points[i];
            }
        }

        maxLen = maxRunLength;
    }

    bool LineUtils::GetMinMaxIndicies(float pixels[], int len, int &minIndex, int &maxIndex) {
        bool isEdge = false;
        bool isPositive = true;

        int numCrossings = 0;

        minIndex = 0;
        maxIndex = 0;

        float avg = 0;

        for (int i = 0; i < len; i++) {
            avg += pixels[i];
        }

        avg = avg / (float) len;        

        if (pixels[0] > avg)
            isPositive = true;
        else
            isPositive = false;

        for (int i = 0; i < len; i++) {
            if (pixels[i] < pixels[minIndex]) {
                minIndex = i;
            } else if (pixels[i] > pixels[maxIndex]) {
                maxIndex = i;
            }

            if (isPositive && pixels[i] < avg) {
                isPositive = false;
                numCrossings++;
            } else if (!isPositive && pixels[i] > avg) {
                isPositive = true;
                numCrossings++;
            }
        }

        if (numCrossings < 3)
            return true;
        else
            return false;
    }

    float LineUtils::CalculateGradient(IppiPoint points[], float pixels[], int len, int minIndex, int maxIndex) {
        float lAvg = 0;
        float hAvg = 0;

        if (minIndex > 0 && minIndex < len - 1) {
            lAvg = (pixels[minIndex] + pixels[minIndex - 1] + pixels[minIndex + 1]) / 3.0;
        } else if (minIndex > 1) {
            lAvg = (pixels[minIndex] + pixels[minIndex - 1] + pixels[minIndex - 2]) / 3.0;
        } else if (minIndex < len - 2) {
            lAvg = (pixels[minIndex] + pixels[minIndex + 1] + pixels[minIndex + 2]) / 3.0;
        } else {
            lAvg = pixels[minIndex];
        }

        if (maxIndex > 0 && maxIndex < len - 1) {
            hAvg = (pixels[maxIndex] + pixels[maxIndex - 1] + pixels[maxIndex + 1]) / 3.0;
        } else if (maxIndex > 1) {
            hAvg = (pixels[maxIndex] + pixels[maxIndex - 1] + pixels[maxIndex - 2]) / 3.0;
        } else if (maxIndex < len - 2) {
            hAvg = (pixels[maxIndex] + pixels[maxIndex + 1] + pixels[maxIndex + 2]) / 3.0;
        } else {
            hAvg = pixels[maxIndex];
        }

        float h = hAvg - lAvg;
        float t = abs(h / (float) (points[maxIndex].x - points[minIndex].x));

        if (t > 0)
            return t > MaxGradient ? MaxGradient : t;
        else
            return MaxGradient;
    }

    float LineUtils::GetAverage(float gradients[], int count) {
        int zerosCount = 0;
        int minValIndex = 0, maxValIndex = 0;

        for (int i = 0; i < count; i++) {
            if (gradients[i] == 0)
                zerosCount++;

            if (gradients[i] > gradients[maxValIndex])
                maxValIndex = i;
            else if (gradients[i] < gradients[minValIndex])
                minValIndex = i;
        }

        gradients[minValIndex] = 0;
        gradients[maxValIndex] = 0;

        zerosCount += 2;

        if (zerosCount < 6) {
            for (int i = 0; i < count; i++) {
                if (gradients[i] > gradients[maxValIndex])
                    maxValIndex = i;
                else if (gradients[i] < gradients[minValIndex])
                    minValIndex = i;
            }
        }

        gradients[minValIndex] = 0;
        gradients[maxValIndex] = 0;

        zerosCount += 2;

        if (zerosCount < 6) {
            for (int i = 0; i < count; i++) {
                if (gradients[i] > gradients[maxValIndex])
                    maxValIndex = i;
                else if (gradients[i] < gradients[minValIndex])
                    minValIndex = i;
            }
        }

        gradients[minValIndex] = 0;
        gradients[maxValIndex] = 0;

        float r = 0;
        zerosCount = 0;
        for (int i = 0; i < count; i++) {
            if (gradients[i] > 0) {
                r += gradients[i];
                zerosCount++;
            }
        }

        if (zerosCount == 0)
            return 0;
        else
            return r / (float) zerosCount;
    }
}

Gradient Calculation

If you remember how the Hough parameters were determined (in polar form, see figure below), it is not difficult to obtain the pixel coordinates centered around the points on the detected line.

Region selection for gradient calculation

In fact, we can formulate a line that is perpendicular to the line section detected during Hough transform, and use the line section that is within a predefined region (e.g. the between the dotted lines) to calculate the gradients of luminance. The following code snippet shows how the perpendicular line’s parameters are obtained.

    /**
     * Get the equation parameters for the line that passes through (x,y) and is perpendicular
     * to the line specified by parameters (p0, theta0) in normal form.
     *
     * @param p0 : distance to line from origin.
     * @param theta0 : the slope of p0.
     * @param x : x coordinate of the point where the perpendicular line passes through
     * @param y : y coordinate of the point where the perpendicular line passes through
     * @param &p : the perpendicular line's distance from origin.
     * @param &theta : the slope of p.
     **/
    void LineUtils::GetPerpendicularLineParameters(float p0, float theta0, float x, float y, float &p, float &theta) {
        float x0 = p0 * cos(theta0);
        float y0 = p0 * sin(theta0);

        p = sqrt((x0 - x)*(x0 - x) + (y0 - y)*(y0 - y));

        float a1 = theta0 - PI / 2.0;
        float a2 = theta0 + PI / 2.0;

        //d=|x0 * cos a + y0 * sin a - p|
        float d1 = abs(x * cos(a1) + y * sin(a1) - p);
        float d2 = abs(x * cos(a2) + y * sin(a2) - p);

        if (d1 < d2)
            theta = a1;
        else
            theta = a2;
    }

In an ideal situation, the gradient of the line points obtained via the method above looks like the figures below, where the edges are clearly identified.

Edge (dark to bright)

Edge (dark to bright to dark)

Sometimes, when the lighting condition is poor, the image would appear to be “grainy”, which sometimes led to poor line detection. For instance, the following figure shows the the gradient when the region around the detected edge is grainy:

None-Edge

We use the number of times the luminance increases above or decreases below its mean along the perpendicular line interval as a measure of whether we accept the detection results as gradients or not. Typically when such number of crossings is less than 3 (see the first two images above) the curve is either monotonic or has a single peak, we assume that gradients can be correctly calculated and if the crossings are more than 3 we discard the results. The gradient is calculated as the slope of the curve. In the examples above, we used ten pixels on each side of the Hough line to calculate gradients.

Image Regions

For images with complex contents, it becomes difficult for the Hough transform to reliably identify line structures within the image. Future more, certain photography techniques (i.e. Bokeh) leave portions of images deliberately blurred. Without dividing image into different sub-regions, the classification results would be compromised.

Thus, images are divided into 9 (3×3) sub-images after Canny edge detection, and Hough transform is performed against each sub-images. The figure below illustrates how an image is divided:

Image divided into 3x3 sub-images (Microsoft Research Digital Image)

This technique is especially useful when portions of images are deliberately blurred, like the image shown above. It also helps the line detection accuracy when the image contains complex scenes. By dividing up the image, each sub area’s complexity is greatly reduced. Other methods in scene separation might achieve even better results, but it is out of the scope for our discussion here.

In my next post, I will show some results obtained from using the method mentioned in this and the previous articles and will also discuss its limitations.

Experience tells us that blur images tend to contain less details then their sharper counterparts. And the areas where intensity transitions occur (e.g. the border of an object) are more well defined in clear images. Mathematically speaking, the slope of the intensity transition is statistically deeper in clear images than blur ones. Since whether an image is blurred or not is not affected by color space, it is sufficient to perform detection in the luminance space (i.e. gray scale images):

\[I=0.299R\times0.587G\times0.114B\]

Canny Edge Detection

Thus the very first step in deciding whether an image or an area within an image is blurred is to use some sort of edge detection algorithms to obtain a collection of the edges in the image.

Canny edge detection is a good candidate since it is optimal in terms of good detection and localization. And hysteresis is used to reduce streaking and thus Canny edge detection achieves relatively continuous edge boundaries comparing to other edge detection methods.

In one of my previous posts, I discussed Canny edge detection using auto thresholding utilizing Intel’s Integrated Performance Primitives (IPP). I used the same algorithm here for the image pre-processing process.

Hough Transform

In order to analyze the gradients along detected edges, it is necessary to first parameterize them. Hough transform comes in handy for this task.

While Hough transform is capable of identifying arbitrary shapes, for the purpose of detecting image blurs simple line detection is more robust. Besides, IPP has an implementation for line detection using Hough transform out of the box.

Since our goal is to determine the quality of the image within a region of interest, we do not need to analyze all the edges identified within that region. But rather, we could select a few based on some pre-determined criteria that would maximize our ability to correctly determine the luminance gradients.

The following code snippet shows my implementation of the edge parameterization method using IPP:

    bool CompareIppiPoint(IppiPoint &p1, IppiPoint &p2) {
        if (p1.x == p2.x) {
            return p1.y < p2.y;
        } else {
            return p1.x < p2.x;
        }
    }

    void IPPGrayImage::HoughLine(IppPointPolar delta, int threshold, int maxLineCount, int* pLineCount, IppPointPolar pLines[], list<IppiPoint> pList[]) {
        IppStatus sts;
        IppiSize roiSize = {_width, _height};

        int bufSize;
        sts = ippiHoughLineGetSize_8u_C1R(roiSize, delta, maxLineCount, &bufSize);
        assert(sts == ippStsNoErr);
        Ipp8u * pBuf = ippsMalloc_8u(bufSize);

        Ipp8u *imgBuf;
        int stepSize;
        imgBuf = ippiMalloc_8u_C1(_width, _height, &stepSize);

        sts = ippiConvert_32f8u_C1R(_imgBuffer, _width * PIXEL_SIZE, imgBuf, _width, roiSize, ippRndNear);
        assert(sts == ippStsNoErr);
        assert(imgBuf != NULL);

        sts = ippiHoughLine_8u32f_C1R(imgBuf, _width, roiSize, delta, threshold, pLines, maxLineCount, pLineCount, pBuf);
        assert(sts == ippStsNoErr);

        //d=|x0 * cos a + y0 * sin a - p|
        int val = 0;
        float d;
        for (int x = 0; x < _width; x++) {
            for (int y = 0; y < _height; y++) {
                if (imgBuf[x + y * _width] > 0) {
                    val = imgBuf[x + y * _width];

                    for (int i = 0; i < *pLineCount; i++) {
                        d = abs((float) cos(pLines[i].theta) * (float) x + (float) sin(pLines[i].theta) * (float) y - abs(pLines[i].rho));
                        if (d < threshold) {
                            IppiPoint p;
                            p.x = x;
                            p.y = y;

                            pList[i].push_back(p);
                        }
                    }
                }
            }
        }

        for (int i = 0; i < *pLineCount; i++) {
            pList[i].sort(CompareIppiPoint);
        }

        ippsFree(pBuf);
        ippiFree(imgBuf);
    }

Note that the selection for delta is crucial for the line detection quality. In the code above, up to maxLineCount number of lines are detected and each line’s parameters are stored in pLines[]. The edge image pixel coordinates within a given range that is less than threshold are collected into the list. Because the Hough detection does not indicate the begin and the end point of a line, we need to iterate through the pixels in pList[] and find the sections that the detected lines pass through. The image below illustrates how the edge regions are chosen based on detected line parameters. Image features within a region between the dotted line are recorded based on the distances to the line defined by:
\[d=\vert x_0cos\alpha+y_0sin\alpha-p\vert\]

Region selection for gradient calculation

In practice, for each parameterized line I chose to select the longest section where the line approximates a section of the edge. Other line sections can be used as well, but the longest portion tends to offer better classification results. The code is shown below, and the thickened section in the figure above illustrates the selected section.

    void LineUtils::GetLongestConnectedLinePoints(IppiPoint points[], int len, int threshold, IppiPoint lpoints[], int &maxLen) {
        int maxIndexEnd = 0, curRunLength = 0, maxRunLength = 0;

        lpoints[curRunLength] = points[0];

        for (int i = 1; i < len; i++) {
            if ((abs(points[i].x - lpoints[curRunLength].x) > threshold) || (abs(points[i].y - lpoints[curRunLength].y) > threshold)) {
                if (curRunLength > maxRunLength) {
                    maxRunLength = curRunLength;
                    maxIndexEnd = i;
                }
                curRunLength = 0;
                lpoints[curRunLength] = points[i];
            } else {
                if (curRunLength >= maxLen) {
                    maxRunLength = maxLen;
                    break;
                }

                curRunLength++;
                lpoints[curRunLength] = points[i];
            }
        }

        for (int i = maxIndexEnd - maxRunLength - 1; i < maxIndexEnd; i++) {
            if (i - (maxIndexEnd - maxRunLength) - 1 < maxRunLength) {
                lpoints[i - (maxIndexEnd - maxRunLength - 1)] = points[i];
            }
        }

        maxLen = maxRunLength;
    }

In my next post, I will continue with the gradient calculation and some methods to enhance the detection accuracies.

Background

Image blur is typically caused by

• Motion (e.g. the relative movement between the camera and the object during exposure)
• Out-of-focus
• Low lighting condition

Other types of image blur may also occur in photography (such as Bokeh). And it is desirable to be able to automatically distinguish desired image blur (e.g. Bokeh caused by camera lens with a shallow depth of field) from un-intended blur (e.g. out of focus).

When reference images (e.g. a series of images with different focus settings) are present, detecting image blur is a relatively simple task. For instance, in passive auto-focus cameras, a series of scene images are captured with progressive focus settings. And the intensity differences are calculated within the same region across these different images. Thus, the image with the highest intensity difference corresponds to the correct focus setting. In Active-focus cameras, image blur detection problem is circumvented by measuring the distance between the lens and the object.

The problem becomes more difficult if we are only given a single image. Since many parameters that we used above in camera auto-focusing are not present in a single image setting, we could not reliably infer image sharpness by the method used in passive auto-focusing as we do not have sufficient knowledge to re-construct the series of images necessary for comparison.

We can however, tell whether an image is in-focus by calculating the intensity differences along the edges in an image. If the calculated intensity is higher than a predefined threshold, we deduce that the image is sharp. And if the calculated intensity is lower than a predefined threshold, we conclude that the image is blurred. So now we shifted the problem to identifying such optimal regions where the intensities are calculated.

Algorithm Overview

In this algorithm, we first use Canny edge detection to obtain the edges in the image. The edges are then parameterized using Hough transform. We then calculate the pixel gradients along the parameterized lines detected and finally we use the gradients to decide whether the image is blurred.

I will discuss some technical and implementation details in the up-coming posts. Stay tuned.

For those who are impatient, the function to perform recursive directory search is here:

#include <sys/types.h>
#include <sys/stat.h>
#include <dirent.h>
#include <errno.h>
#include <vector>
#include <string>
#include <iostream>
#include <boost/regex.hpp>

void GetFileListing(vector<string> &files, string dir, string filter, bool ignoreCase) {
    DIR *d;
    if ((d = opendir(dir.c_str())) == NULL) return;
    if (dir.at(dir.length() - 1) != '/') dir += "/";

    struct dirent *dent;
    struct stat st;
    boost::regex exp;

    if (ignoreCase)
        exp.set_expression(filter, boost::regex_constants::icase);
    else
        exp.set_expression(filter);

    while ((dent = readdir(d)) != NULL) {
        string path = dir;

        if (string(dent->d_name) != "." && string(dent->d_name) != "..") {
            path += string(dent->d_name);
            const char *p = path.c_str();
            lstat(p, &st);

            if (S_ISDIR(st.st_mode)) {
                GetFiles(files, (path + string("/")).c_str(), filter, ignoreCase);
            } else {
                if (filter == ".*") {
                    files.push_back(path);
                } else {
                    if (boost::regex_match(string(dent->d_name), exp)) files.push_back(path);
                }
            }
        }
    }

    closedir(d);
}

I used boost library to perform regular expression matches for file names. If you just want to obtain a listing of all the files, you can do without using the boost library.

The following code snippet demonstrates how to use the function. The results are stored in a vector container passed in. Note that the “filter” parameter needs standard regular expressions (so if you are looking for any files, the expression should be .* instead of just *) to work properly.

The code should be pretty self-explanatory. If ignoreCase is set to true, then the match will be case-insensitive.

vector<string> files;

FileUtils::GetFiles(files,"/tmp", ".*", true);
for (int i = 0 ; i < files.size(); i++) {
    cout << files[i] << endl;
}

Here I will examine a few commonly used method in measuring time intervals under Linux. All of the following timing routines are timed against the same OpenMP parallel for loop (on a quad-core CPU, the parallel for will spawn four concurrent threads).

time()

The time() function returns time with the accuracy to a second. So this function is generally useful for measuring long-running processes.

clock()

In single-core systems, clock() is often used for time measurements. The resolution of this timer is determined by CLOCKS_PER_SEC and is usually a microsecond. Since it determines the number of CPU clock cycles elapsed, it is not particularly useful in measuring time on a multi-core processor system when there are concurrent executing threads as the result of clock() function is the accumulation of CPU clocks across all active CPUs. On a quad-core system, if all cores are at full utilization then the result time is roughly four times the wall time.

gettimeofday()

Similar to the clock() function, gettimeofday() has a resolution up to one microsecond. As the function name suggests, gettimeofday() measures the wall time and thus is suitable for time measurement in multi-core, multi-cpu systems.

rdtsc

The time stamp counter is available on most modern CPUs (since Pentium). There are many implementations based on rdtsc (e.g. on Windows systems, the Win32 API call QueryPerformanceCounter). Implementation based on rdtsc is generally very accurate (with resolution up to one nanosecond) but depending on implementation, its accuracy might be susceptible to CPU clock throttling (common in mobile CPUs). In my implementation below, the rdtsc results are divided by the CPU frequency.

grep “cpu MHz” /proc/cpuinfo | cut -d’:’ -f2

This implementation assumes that CPU frequency remains constant during operations, which could lead to poor accuracy should the CPU frequency change during the measurement. For desktop CPU though, this is less of a concern however.

clock_gettime

Like rdtsc, this function has a nanosecond accuracy and is available on all POSIX compliant systems.

Intel Threading Building Block also provides a timer function tick_count::now() and the time can easily measured using the code snippet below:

    t_start = tick_count::now();
    //statements
    t_end = tick_count::now();
    cout << (t_end - t_start).seconds() * 1000 << " ms" << endl;

The following lists the code for time measuring using the methods mentioned above.

#include <iostream>
#include <stdio.h>
#include <stdlib.h>
#include <sys/time.h>
#include <time.h>
#include <ctime>

using namespace std;

void Foo() {
#pragma omp parallel
    {
        for (long i = 0; i < 50000; i++)
            for (long j = 0; j < 50000; j++);
    }

}

unsigned long long rdtsc() {
    unsigned a, d;

    __asm__ volatile("rdtsc" : "=a" (a), "=d" (d));

    return ((unsigned long long) a) | (((unsigned long long) d) << 32);
}

void Time() {
    time_t t1, t2;

    time(&t1);
    Foo();
    time(&t2);

    cout << "time() : " << t2 - t1 << " s" << endl;
}

void Clock() {
    clock_t c1 = clock();
    Foo();
    clock_t c2 = clock();
    cout << "clock() : " << (float) (c2 - c1) / (float) CLOCKS_PER_SEC << " s" << endl;
}

void GetTimeOfDay() {
    timeval t1, t2, t;
    gettimeofday(&t1, NULL);
    Foo();
    gettimeofday(&t2, NULL);
    timersub(&t2, &t1, &t);

    cout << "gettimeofday() : " << t.tv_sec + t.tv_usec / 1000000.0 << " s" << endl;
}

void RDTSC() {
    unsigned long long t1, t2;

    t1 = rdtsc();
    Foo();
    t2 = rdtsc();

    cout << "rdtsc() : " << 1.0 * (t2 - t1) / 3199987.0 / 1000.0 << " s" << endl;
}

void ClockGettime() {
    timespec res, t1, t2;
    clock_getres(CLOCK_REALTIME, &res);

    clock_gettime(CLOCK_REALTIME, &t1);
    Foo();
    clock_gettime(CLOCK_REALTIME, &t2);

    cout << "clock_gettime() : "
         << (t2.tv_sec - t1.tv_sec)  + (float) (t2.tv_nsec - t1.tv_nsec) / 1000000000.0
         << " s" << endl;
}

int main() {
    cout.setf(ios::fixed);
    cout.setf(ios::showpoint);
    cout.precision(5);

    Time();
    Clock();
    GetTimeOfDay();

    RDTSC();
    ClockGettime();

    return (EXIT_SUCCESS);
}

And here is the output from my quad-core computer in debug mode.

time() : 6 s
clock() : 21.85000 s
gettimeofday() : 5.67368 s
rdtsc() : 5.65957 s
clock_gettime() : 5.65894 s

After a quick search on ImageMagick’s site I realized that I was missing the following libraries:

libpng12
libjpeg62

Note, that you might want to use the following commands to find out the exact package names:

sudo apt-cache search libpng
sudo apt-cache search libjpeg

sudo apt-cache search libjpeg
And then use the following commands to install the packages:

sudo apt-get install libpng12-0 libpng12-dev
sudo apt-get install libjpeg62 libjpeg62-dev

Note that after that, you will need to re-configure and re-build the Magick++ library (e.g. ./configure, ./make ./make install) so that Magick++ library can be linked correctly with the above libraries.

The simplest way is to use the mean value of the gray scale image pixel values. As a rule of thumb, we set the low threshold to 0.66*[mean value] and set the high threshold to 1.33*[mean value]. Another way is to use the median color in the gray scale image and uses 0.66*[median value] and 1.33*[median value] accordingly. For typical images, these two methods achieve comparable results.

For example, the following shows the picture of a building along with its histogram (original image from Microsoft Research Digital Image. Please see Microsoft Research Digital Image License Agreement for more information):

Building

Building Histogram

The following shows the edge detection results using Canny algorithm (left image uses mean value auto-thresholding, right image uses median value auto-thresholding) and the results exhibit very little visible differences.

Building (Canny Mean)

Building (Canny Median)

However, for images has non-equalized histogram (see the picture of cloud and its histogram below):

Cloud

Cloud Histogram

Canny Edge detection result based on mean value auto-thresholding is pretty poor (see image on the left below), while edge detection based on median value auto-thresholding achieved much better result (see image on the right below)

Cloud (Canny Mean)

Cloud (Canny Median)

Alternatively, we could have performed histogram equalization on the image first before applying Canny edge detection with mean auto-thresholding:

Cloud Equalized

Cloud Equalized Histogram

And after image equalization, both mean and median value auto-thresholding achieved similar results.

Cloud Equalized (Canny Mean)

Cloud Equalized (Canny Median)

So the Canny edge detection using median value auto-thresholding seems to adapt to different types of images very well (note selecting the median value selection can be thought as equalizing the histogram, except that the pixel values are not changed during such operation).

The following is the code listing for the histogram calculation using IPP (based on the image class I created earlier)

/** @brief Get the min max mean value statistics for the current image
 *   @param min, max, mean: these are output parameters that are passed
 *         back by reference.
 */
void IPPGrayImage::MinMaxMean(float& min, float& max, double& mean)
{
    IppStatus sts;
    IppiSize origImgSize = {_width, _height};

    sts = ippiMinMax_32f_C1R(_imgBuffer, _width * PIXEL_SIZE, origImgSize, &min, &max);
    assert(sts == ippStsNoErr);
    sts = ippiMean_32f_C1R(_imgBuffer, _width * PIXEL_SIZE, origImgSize, &mean, ippAlgHintFast);
    assert(sts == ippStsNoErr);
}

/** @brief Calculate the histogram of the image
 *   @param nLevel: the number of bins in the histogram
 *        levels: this is the optional levels user can pass in (histogram will be then
 *                calculated with these levels instead of the uniform levels by default.
 *   @return an integer array which contains the histogram.
 *   @note the histogram is by default calculated using uniform bins across the color range.
 */
unsigned int * IPPGrayImage::GetHistogram(unsigned int nLevel, float levels[])
{
    IppStatus sts;
    Ipp32f* l = new Ipp32f[nLevel];
    IppiSize origImgSize = {_width, _height};

    unsigned int* bins = new unsigned int[nLevel - 1];

    float minVal = 0, maxVal = 0, stepVal = 0;
    double meanVal = 0;
    if (levels != NULL)
    {
        for (unsigned int i = 0; i < nLevel; i++)
        {
            l[i] = levels[i];
        }
    }
    else
    {
        MinMaxMean(minVal, maxVal, meanVal);
        stepVal = (maxVal - minVal) / (float) nLevel;

        for (unsigned int i = 0; i < nLevel; i++)
        {
            l[i] = minVal + stepVal * i;
        }
    }

    sts = ippiHistogramRange_32f_C1R(_imgBuffer, _width * PIXEL_SIZE, origImgSize, (Ipp32s*) bins, (Ipp32f*) l, nLevel);
    return bins;
}

In my opinion, the above three IDEs all have their strengths and weaknesses depending on what kind of project you are working on. Here are some of my observations.

KDevelop is probably the most comprehensive IDE of the three. This should not come as a surprise as it has been around for more than 10 years and it bas been the de facto development environment for most of the KDE development work. It is very feature rich and you can use it to develop many different types of applications natively out of box (e.g. KDE, GTK+, Qt, wxWidgets, etc). If you are developing GNU style applications, you will benefit from the Automake project type if provides. Besides the vast functionalities KDevelop provides, it is also very fast, efficient and stable.

Nonetheless, KDevelop is not the most intuitive IDE and does not suit small projects (e.g. prof of concept code) well as the initial project setup can be time consuming.

Code::Blocks is a very capable IDE for C++ development as well. It offers many project templates even though it does not offer native KDE project types. This should not be a problem to most people however. Among the features I like the most is that it does not require explicit make file configuration and the build dependencies are inferred by default. This makes it very attractive for rapid prototyping. Debugging under Code::Blocks is also a pleasant experience. It also integrates (at least in the later SVN versions) Valgrind‘s MemCheck and Cachegrind, which are very useful for detecting memory leaks and tweaking algorithms for the maximum performance.

The latest stable version of Code::Blocks is 8.02, it is a little dated as a lot of functionalities have been added in the later SVN builds. If you do not require the most stability (I have run into some issues recently), using SVN build should not be a problem. The editor (e.g. syntax highlighting, collapsible regions) is a little bit buggy though and the contextual help does not always work to the level of detail I desired.

NetBeans C++ IDE is probably the most beautiful one among the three. It offers the most detailed syntax highlighting, and can be configured to display class hierarchy and library function information. The refactor tool works pretty well and is certainly a boon to large scale development. Its contextual help is also of top-notch.

All of these come at a cost of course. NetBeans C++ IDE is the most resource intensive among the three. It can easily use 500 MB memory when doing development and can be sluggish at times. It also comes with a very limited project template (e.g. no out-of-box project templates for Qt, wxWidgets). Certain settings are hard to get at as well. Nevertheless, if I am primarily writing back-end code, NetBeans C++ IDE could easily earn my top choice.

Some people like Anjuta and compare it favorably to Code::Blocks. But I haven’t got a chance to use it yet.

In this article, I will show a simple example of creating a wrapper class using IPP and Magick++. The example I am going to show can be used to calculate the 2-dimensional FFT spectrum of a gray-scale image. This framework can be easily extended to include other algorithms that can be applied to an image using IPP.

Before I show the implementation details, let me first show how easy it is to use the class. The code snippet below shows how to read in an image file, apply 2D FFT with and without a Hamming window and save the results into image files.

    IPPGrayImage *img, *img1;

    img = new IPPGrayImage();
    img->LoadFromFile(IMAGE_FILE);

    img1 = img->Clone();
    img1 = img1->FFT(true);
    img1->SaveToFile(IMAGE_HOME + "/test_fftmag.jpg");
    img1 = img->Clone();
    img1 = img->ApplyHammingWindow();
    img1->SaveToFile(IMAGE_HOME + "/test_hamming.jpg");
    img1 = img1->FFT(true);
    img1->SaveToFile(IMAGE_HOME + "/test_fftmag_hamming.jpg");

And for the following IMAGE_FILE,

Test image used for 2D FFT

Here are the results for FFT spectrum with and without hamming window:

Hamming window applied

FFT spectrum (without Hamming window)

FFT spectrum with Hamming window

The header file for the class is as follows:

#ifndef IPPGRAYIMAGE_H
#define IPPGRAYIMAGE_H

#include <Magick++/Image.h>
#include <Magick++.h>
#include <ipp.h>

using namespace std;
using namespace Magick;

namespace KDW
{
    class IPPGrayImage
    {
    public:
        unsigned int PIXEL_SIZE;

        IPPGrayImage();
        IPPGrayImage(const unsigned int width, const unsigned int height);
        IPPGrayImage(Ipp32f *imgBuffer, const unsigned int width, const unsigned int height);
        IPPGrayImage(const IPPGrayImage& other);
        virtual ~IPPGrayImage();
        IPPGrayImage& operator=(const IPPGrayImage& other);

        void LoadFromFile(string fileName);
        void SaveToFile();
        void SaveToFile(string fileName);

        inline float GetPixel(unsigned int col, unsigned int row) {return _imgBuffer[row * _width + col];}
        inline void SetPixel(unsigned int col, unsigned int row, float clr) {_imgBuffer[row * _width + col] = clr;}

        unsigned int GetWidth() { return _width;}
        unsigned int GetHeight() { return _height;}

        Ipp32f* GetImageBuffer() { return _imgBuffer;}
        Image* GetImage() { return _img;}

        IPPGrayImage* Clone();
        IPPGrayImage* ApplyHammingWindow();
        IPPGrayImage* FFT(bool fftShift = false);
    protected:
    private:
        unsigned int _width;
        unsigned int _height;

        Image* _img;
        Pixels* _view;
        PixelPacket* _pixels;
        Ipp32f* _imgBuffer;
        string _fileName;

        void Init();
    };
}
#endif // IPPGRAYIMAGE_H

And here’s the implementation for the class:

#include <assert.h>
#include <math.h>

#include "IPPGrayImage.h"

namespace KDW
{
    /** @brief Constructor()
     *  Initialize image buffer.
     */
    IPPGrayImage::IPPGrayImage()
    {
        Init();
    }

    /** @brief Constructor(width, height)
     *  Initialize an image size of width x height.
     */
    IPPGrayImage::IPPGrayImage(const unsigned int width, const unsigned int height)
    {
        Init();

        _width = width;
        _height = height;

        int stepByte = 0;
        _imgBuffer = ippiMalloc_32f_C1(_width, _height, &stepByte);
    }

    /** @brief Constructor(imgBuffer, width, height)
     *  Initilize from an Ipp32f buffer (width x height)
     */
    IPPGrayImage::IPPGrayImage(Ipp32f *imgBuffer, const unsigned int width, const unsigned int height)
    {
        Init();

        _width = width;
        _height = height;
        _imgBuffer = imgBuffer;
    }

    /** @brief Copy Constructor
     */
    IPPGrayImage::IPPGrayImage(const IPPGrayImage& other)
    {
        _width = other._width;
        _height = other._height;

        int stepByte = 0;

        _imgBuffer = ippiMalloc_32f_C1(_width, _height, &stepByte);

        for (unsigned int row = 0; row < _height ; row++)
        {
            for (unsigned int column = 0; column < _width ; column++)
            {
                _imgBuffer[column + row * _width] =other._imgBuffer[column + row * _width];
            }
        }

        if (other._pixels == NULL) _pixels = NULL;
    }

    /** @brief Overload =
     */
    IPPGrayImage& IPPGrayImage::operator=(const IPPGrayImage& rhs)
    {
        if (this == &rhs) return *this; // handle self assignment

        return *this;
    }

    /**
     * @brief Destructor
     */
    IPPGrayImage::~IPPGrayImage()
    {
        ippFree(_imgBuffer);
        delete _img;
        delete _view;
    }

    /**
     * @brief Common initialization code
     */
    void IPPGrayImage::Init()
    {
        PIXEL_SIZE = sizeof(Ipp32f);
        _pixels = NULL;
        _imgBuffer = NULL;
        _img = NULL;
    }

    /** @brief Load an image from file
      */
    void IPPGrayImage::LoadFromFile(string fileName)
    {
        _img = new Image(fileName);
        Geometry g = _img->size();

        _width = g.width();
        _height= g.height();

        _view = new Pixels(*_img);
        _pixels = _view->get(0,0, _width, _height);

        int stepByte = 0;
        _imgBuffer = ippiMalloc_32f_C1(_width, _height, &stepByte);

        for (unsigned int row = 0; row < _height ; row++)
        {
            for (unsigned int column = 0; column < _width ; column++)
            {
                PixelPacket *p = &_pixels[column + row * _width];
                Color c = Color(p->red, p->green, p->blue);
                _imgBuffer[column + row * _width] = c.intensity();
            }
        }
    }

    /** @brief Save the current image buffer to file
      */
    void IPPGrayImage::SaveToFile()
    {
        SaveToFile("");
    }

    /** @brief SaveToFile(fileName)
     *  Saves the current image buffer to a file (by file name).
     */
    void IPPGrayImage::SaveToFile(string fileName)
    {
        if (_img != NULL && _pixels != NULL)
        {
            for (unsigned int y = 0; y< _height ; y++)
            {
                for (unsigned int x = 0; x < _width; x++)
                {
                    float clr = (float) _imgBuffer[x + y * _width];
                    _pixels[x+ y * _width] = Color(clr, clr, clr);
                }
            }
            _view->sync();
            _img->syncPixels();

            if (fileName == "")
            {
                _img->write(_fileName);
            }
            else
            {
                _img->write(fileName);
            }
        }
        else
        {
            Image img(Geometry(_width, _height),"white");

            for (unsigned int y = 0; y< _height ; y++)
            {
                for (unsigned int x = 0; x < _width; x++)
                {
                    Color c;
                    float clr = (float) _imgBuffer[x + y * _width];
                    img.pixelColor(x,y, Color(clr, clr, clr));
                }
            }

            img.write(fileName);
        }
    }

    /** @brief Clone
    *   Duplicate the current image to another IPPGrayImage object.
    *   @return an IPPGrayImage pointer to the cloned image
    */
    IPPGrayImage* IPPGrayImage::Clone()
    {
        IPPGrayImage *newImg;

        newImg = new IPPGrayImage(_width, _height);

        int stepByte = 0;
        newImg->_imgBuffer = ippiMalloc_32f_C1(_width,_height, &stepByte);

        for (unsigned int y = 0 ; y < _height ; y++)
        {
            for (unsigned int x = 0 ; x < _width ; x++)
            {
                newImg->_imgBuffer[x + y * _width] = _imgBuffer[x + y * _width];
            }
        }

        return newImg;
    }

    /** @brief Apply Hamming window to the image
     *  @return an IPPGrayImage pointer to the processed image
     */
    IPPGrayImage* IPPGrayImage::ApplyHammingWindow()
    {
        IPPGrayImage *newImg;
        newImg = new IPPGrayImage(_width , _height);
        IppiSize srcImgSize = {_width, _height};

        IppStatus sts;
        int stepByte;
        Ipp32f *imgCache = ippiMalloc_32f_C1(_width , _height , &stepByte);

        sts = ippiWinHamming_32f_C1R(_imgBuffer, _width * PIXEL_SIZE, imgCache, _width * PIXEL_SIZE, srcImgSize);
        assert(sts ==ippStsNoErr);

        for (unsigned int y = 0; y< _height; y++)
        {
            for (unsigned int x = 0; x < _width; x++)
            {
                newImg->_imgBuffer[x+ y * _width] = imgCache[x + y * _width];
            }
        }

        return newImg;
    }

    /** @brief Perform FFT on the image and returns the magnitude component
     *  @param fftShift: if it is true, the the result is with
     *         zero-frequency component shifted to center of spectrum
     *  @return the magnitude FFT component
     */
    IPPGrayImage* IPPGrayImage::FFT(bool fftShift)
    {
        IPPGrayImage *newImg;
        IppiFFTSpec_R_32f *spec;
        IppStatus sts;

        unsigned int n = (int) (logf((float) _width) / logf(2.0f));
        unsigned int m = (int) (logf((float) _height) / logf(2.0f));

        unsigned int N = pow(2, n);
        unsigned int M = pow(2, m);

        if (N < _width)
        {
            n = n + 1;
            N = pow(2, n);
        }

        if (M < _height)
        {
            m = m + 1;
            M = pow(2, m);
        }

        int stepByte;
        Ipp32f *src = ippiMalloc_32f_C1(M , N , &stepByte);
        Ipp32f *dst = ippiMalloc_32f_C1(M , N , &stepByte);
        Ipp32f *mag = ippiMalloc_32f_C1(M , N , &stepByte);

        IppiSize srcImgSize = {_width, _height};
        IppiSize dstImgSize = {N, M};

        sts = ippiCopyConstBorder_32f_C1R(
                  _imgBuffer, _width * PIXEL_SIZE, srcImgSize,
                  src,  N * PIXEL_SIZE, dstImgSize,
                  0,0,0);
        assert(sts ==ippStsNoErr);

        sts = ippiFFTInitAlloc_R_32f(&spec, n , m, IPP_FFT_DIV_BY_SQRTN, ippAlgHintAccurate);
        assert(sts ==ippStsNoErr);

        sts = ippiFFTFwd_RToPack_32f_C1R(src, N*PIXEL_SIZE, dst, N*PIXEL_SIZE, spec, 0);
        assert(sts ==ippStsNoErr);

        sts = ippiMagnitudePack_32f_C1R(dst, N*PIXEL_SIZE, mag, N*PIXEL_SIZE, dstImgSize);
        assert (sts ==ippStsNoErr);

        newImg = new IPPGrayImage(N , M);

        if (fftShift)
        {
#pragma omp sections
            {
#pragma omp section
                {
                    for (unsigned int y = 0 ; y < M/2; y++)
                    {
                        for (unsigned int x = 0 ; x < N/2; x++)
                        {
                            newImg->_imgBuffer[x+ y *N] = mag[x + N/2 + (y + M/2) * N];
                        }
                    }
                }
#pragma omp section
                {
                    for (unsigned int y = 0 ; y < M/2; y++)
                    {
                        for (unsigned int x = N/2 ; x < N; x++)
                        {
                            newImg->_imgBuffer[x+ y *N] = mag[x - N/2 + (y + M/2) * N];
                        }
                    }
                }
#pragma omp section
                {
                    for (unsigned int y = M/2 ; y < M; y++)
                    {
                        for (unsigned int x = 0 ; x < N/2; x++)
                        {
                            newImg->_imgBuffer[x+ y *N] = mag[x + N/2 + (y - M/2) * N];
                        }
                    }
                }
#pragma omp section
                {
                    for (unsigned int y = M/2 ; y < M; y++)
                    {
                        for (unsigned int x = N/2 ; x < N; x++)
                        {
                            newImg->_imgBuffer[x+ y *N] = mag[x - N/2 + (y - M/2) * N];
                        }
                    }
                }
            }
        }
        else
        {
            for (unsigned int y = 0; y< M; y++)
            {
                for (unsigned int x = 0; x <N; x++)
                {
                    newImg->_imgBuffer[x+ y * N] = mag[x + y * N];
                }
            }

        }

        return newImg;
    }
}

The above example showed only the FFT function, but virtually all IPP image routines can be accommodated using the wrapper image class above. Intel IPP utilizes many different data types (e.g. Ipp8u, Ipp16s, Ipp32f etc.), but to provide most of the flexibility and compatibility I chose to use only the 32 bit floating data type. For specific implementations, other data types can be used as well.

Since the implementation of many of the functions are threaded, it makes the task of writing high performance applications much easier. Since it is a set of “performance primitives” as the name suggests, it uses its own data structures (e.g. Ipp8u) and does not provide functions to directly inter-operate with data coming from other sources (e.g. image files).

Fortunately, such data conversion is pretty straight forward. In this post, I will illustrate how to convert an image file (e.g. .jpg, .png, .gif) to the data IPP uses, and how to save the result into a standard image file once the processing is done.

Magick++ is a very comprehensive image-processing C++ library and the Image class it provides handles image files quite well. So I chose to use Magic++’s API to convert image files to the data structure IPP uses. In this particular example, I will use a gray level image. But in practice, color images can be easily handled in a similar fashion.

For the code mentioned below, the following headers and namespaces are used:

#include <Magick++/Image.h>
#include <Magick++.h>
#include <ipp.h>

using namespace std;
using namespace Magick;

And the following code shows how to convert a standard image file data into format that is suitable for IPP.

    IppStatus sts;
    Image img("{Image File Name}");
    Geometry g = img.size();

    unsigned int width = g.width();
    unsigned int height= g.height();

    Pixels view(img);
    PixelPacket *pixels = view.get(0,0,width,height);

    int stepByte = 0;
    //allocating a buffer of unsigned char (Ipp8u) for the image.
    Ipp8u *imgCache = ippiMalloc_8u_C1(width,height, &stepByte);

    for (unsigned int row = 0; row < height ; row++)
    {
        for (unsigned int column = 0; column < width ; column++)
        {
            PixelPacket *p = &pixels[column + row * width];
            Color c = Color(p->red, p->green, p->blue);
            double i = c.scaleQuantumToDouble(c.intensity()) * 255;
            imgCache[column + row * width] = (char) i;
        }
    }

The above code snippet first reads the image data into *PixelPacket and the pixel buffer is then converted into a one channel buffer of chars (color value 0-255). Note that the range of the image data Magick++ reads in is between 0 and QuantumRange, which needs to be converted back to the range 0-255 accepted by the Ipp8u buffer. If other types of IPP image buffers are used (e.g. Ipp32f), this scaleQuantumToDouble() conversion may not be necessary. At the end, the image data is converted into the one dimensional array imgCache which can be used by IPP procedures.

Once we are in the IPP data domain, we can proceed with whatever processing we had in mind. Here I will show the code for edge detection using Canny algorithm.

    IppiSize orgImgSize = {width, height};
    IppiSize newImgSize = {width + 2, height + 2};

    Ipp8u *imgCache1 = ippiMalloc_8u_C1(width + 2,height + 2, &stepByte);
    sts = ippiCopyReplicateBorder_8u_C1R(imgCache, width, orgImgSize,  imgCache1,
            width + 2 , newImgSize, 2, 2);
    IppiSize roi = {width, height};

    Ipp32f low=30.0f, high=100.0f;
    int size, size1, srcStep, dxStep, dyStep, dstStep;

    Ipp8u *src, *dst, *buffer;
    Ipp16s *dx, *dy;

    sts = ippiFilterSobelNegVertGetBufferSize_8u16s_C1R(
            roi, ippMskSize3x3, &size);
    sts = ippiFilterSobelHorizGetBufferSize_8u16s_C1R(
            roi, ippMskSize3x3, &size1);

    if (size<size1) size=size1;
    ippiCannyGetSize(roi, &size1);
    if (size<size1) size=size1;

    buffer = ippsMalloc_8u(size);
    dx = ippsMalloc_16s(size);
    dy = ippsMalloc_16s(size);
    dst = ippsMalloc_8u(size);

    sts = ippiFilterSobelNegVertBorder_8u16s_C1R (
            imgCache1, width + 2 , dx, (width + 2) * 2 ,
            roi, ippMskSize3x3, ippBorderRepl, 0, buffer);
    sts = ippiFilterSobelHorizBorder_8u16s_C1R(
            imgCache1, width + 2, dy, (width + 2) *2 ,
            roi, ippMskSize3x3, ippBorderRepl, 0, buffer);
    sts = ippiCanny_16s8u_C1R(dx,
            (width + 2) * 2, dy, (width + 2) * 2,
            dst, width, roi, low, high, buffer);

The code shown above is adopted from Intel’s IPP manual for image and video processing (by default it is located at /opt/intel/ipp/{version number}/em64t/doc/ippiman.pdf).

Please pay special attention to how the original image is extended via ippiCopyReplicateBorder_8u_C1R. The image is extended by 2 pixels in each direction because the 3×3 mask used for the filtering operation. I omitted error checking code for simplicity, but in general you need to check the return status of each ippi function call. When the call is successful, the status is ippStsNoErr. If you receive a value other than ippStsNoErr (e.g. ippStsStepErr) you will need to check your buffer size to make sure that they are adjusted according to the data type. For instance, in the code above dx and dy are both 16bit signed integers and thus they both occupy two bytes each.

To save the result image, we convert the pixel buffer back to PixelPacket type. Again we need to convert the data in the buffer (Ipp8u) to the range accepted by Magick++ API.

    for (unsigned int y = 0; y< height ; y++)
    {
        for (unsigned int x = 0; x < width; x++)
        {
            Color c;
            float clr = (float) dst[x + y * width] /255;
            float q = c.scaleDoubleToQuantum(clr);
            pixels[x+ y * width] = Color(q, q, q);
        }
    }

    view.sync();
    img.syncPixels();

    img.write("{Image File Name}");

We can also save the result data into a new image (instead of syncing the data back to the image object holding the original image data) using the code below:

    Image img1(Geometry(width, height),"white");

    for (unsigned int y = 0; y< height ; y++)
    {
        for (unsigned int x = 0; x < width; x++)
        {
            Color c;
            float clr = (float) dst[x + y * width] /255;
            float q = c.scaleDoubleToQuantum(clr);
            img1.pixelColor(x,y, Color(q, q, q));
        }
    }

    img1.write("{Image File Name}");

And finally the buffers used are freed.

    ippiFree(imgCache);
    ippsFree(buffer);

The following images show Canny edge detector in action using the code in this article:

Original

Canny Edge Detector applied

Even though a lot of optimizations have been done in the .Net runtime to make it more efficient, it is apparent that scientific programming still favors C and C++ because that the performance advantage is huge.

In this article, I will examine some matrix multiplication algorithms that are commonly used and illustrate the efficiencies of the various methods. All the tests are done using C++ only and matrices size ranging from 500×500 to 2000×2000. When the matrix sizes are small (e.g. <50), you can pretty much use any matrix multiplication algorithms without observing any significant performance differences. This is largely due to the fact that the typical stable matrix multiplication algorithms are O(n^3) and sometimes array operation overheads outweigh the benefit of algorithm efficiencies. But for matrices of larger dimensions, the efficiency of the multiplication algorithm becomes extremely important.

Since Dmitri’s article has already captured pretty detailed data using the standard matrix multiplication algorithm, I will not repeat his findings in this article. What I intended to show was the performance data of uBLAS, OpenMP, cBLAS and MATLAB.

The following sample code are compiled under Ubuntu 8.10 64 bit (kernel 2.6.24.23) on Intel Q9450@3.2GHz.

Standard Matrix Multiplication (Single Threaded)

This is our reference code. Later on, I will only show the critical portion of the code and not repeat the common portion of code that initializes/finalizes the arrays. Similarly, the timing method used is also the same across all the tests and will be omitted later on.

float **A, **B, **C;

A = new float*[matrix_size];
B = new float*[matrix_size];
C = new float*[matrix_size];

for (int i = 0 ; i < matrix_size; i++)
{
    A[i] = new float[matrix_size];
    B[i] = new float[matrix_size];
    C[i] = new float[matrix_size];
}

for (int i=0; i<matrix_size; i++)
{
    for (int j = 0 ; j < matrix_size; j++)
    {
        A[i][j]=rand();
        B[i][j]=rand();
    }
}

timeval t1, t2, t;
gettimeofday(&t1, NULL);

for (int i = 0 ; i < matrix_size; i++)
{
    for (int j = 0;  j < matrix_size; j++)
    {
        C[i][j] = 0;
        for (int k = 0; k < matrix_size; k++)
        {
            C[i][j] += A[i][k] * B[k][j];
        }
    }
}

gettimeofday(&t2, NULL);
timersub(&t2, &t1, &t);

cout << t.tv_sec + t.tv_usec/1000000.0 << " Seconds -- Standard" << endl;

for (int i = 0 ; i < matrix_size; i++)
{
    delete A[i];
    delete B[i];
    delete C[i];
}

delete A;
delete B;
delete C;

OpenMP With Two Dimensional Arrays

Using OpenMP, we are able to multiple threads via the #pragma omp directives. For the simple algorithm we used here, the speed increase is almost proportional to the number of available cores within the system.

...
#pragma omp parallel for shared(a,b,c)
for (long i=0; i<matrix_size; i++)
{
    for (long j = 0; j < matrix_size; j++)
    {
        float sum = 0;
        for (long k = 0; k < matrix_size; k++)
        {
            sum +=a[i][k]*b[k][j];
        }
        c[i][j] = sum;
    }
}
...

OpenMP With One Dimensional Arrays

Cache locality is poor using the simple algorithm I showed above. The performance can be easily improved however by improving the locality of the references. One way to achieve better cache locality is to use one dimensional array instead of two dimensional array and as you will see later, the performance of the following implementation has as much as 50% speed gains over the previous OpenMP implementation using two dimensional arrays.

float *a, *b, *c;

a = new float[matrix_size * matrix_size];
b = new float[matrix_size * matrix_size];
c = new float[matrix_size * matrix_size];

for (long i=0; i<matrix_size * matrix_size; i++)
{
    a[i]=rand();
    b[i] = rand();
    c[i] = 0;
}

#pragma omp parallel for shared(a,b,c)
for (long i=0; i<matrix_size; i++)
{
    for (long j = 0; j < matrix_size; j++)
    {
        long idx = i * matrix_size;
        float sum = 0;
        for (long k = 0; k < matrix_size; k++)
        {
            sum +=a[idx + k]*b[k * matrix_size +j];
        }
        c[idx + j] = sum;
    }
}

delete a;
delete b;
delete c;

Boost Library uBLAS (Single Threaded)

Boost library provides a convenient way to perform matrix multiplication. However, the performance is very poor compared to all other approaches mentioned in this article. The performance of the uBLAS implementation is largely on par with that using C# (see benchmarks towards the end of the article). Intel’s Math Kernal Library (MKL) 10.1 does provide functionality to dynamically convert code using uBLAS syntax into highly efficient code using MKL by the inclusion of header file mkl_boost_ublas_matrix_prod.hpp. I have not tried it myself though, but the performance should be comparible to algorithms using the native MKL BLAS interface.

By default (without using MKL’s uBLAS capability) though, uBLAS is single threaded and due to its poor performance and I would strongly suggest avoid using uBLAS in any high performance scientific applications.

matrix<float> A, B, C;

A.resize(matrix_size,matrix_size);
B.resize(matrix_size,matrix_size);

for (int i = 0; i < matrix_size; ++ i)
{
    for (int j = 0; j < matrix_size; ++ j)
    {
        A(i, j) = rand();
        B(i, j) = rand();
    }
}

C =prod(A, B);

Intel Math Kernel Library (MKL) cBLAS

Intel’s Math Kernel Library (MKL) is highly optimized on Intel’s microprocessor platforms. Given that Intel developed this library for its own processor platforms we can expect significant performance gains. I am still surprised at how fast the code runs using cBLAS though. In fact, it was so fast that I doubted the validity of the result at first. But after checking the results against those obtained by other means, those doubts were putting into rest.

The cBLAS matrix multiplication uses blocked matrix multiplication method which further improves cache locality. And it is more than thirty times faster then the fastest OMP 1D algorithm listed above! Another benefit is that by default it automatically detects the number of CPUs/cores available and uses all available threads. This behavior greatly simplifies the code since threading is handled transparently within the library.

float *A, *B, *C;

A = new float[matrix_size * matrix_size];
B = new float[matrix_size * matrix_size];
C = new float[matrix_size * matrix_size];

for (int i = 0; i < matrix_size * matrix_size; i++)
{
    A[i] = rand();
    B[i] = rand();
    C[i] = 0;
}

cblas_sgemm(CblasRowMajor, CblasNoTrans, CblasNoTrans,
    matrix_size,  matrix_size,  matrix_size, 1.0, A,matrix_size,
    B, matrix_size, 0.0, C, matrix_size);

MATLAB (Single Threaded)

MATLAB is known for its efficient algorithms. In fact it uses BLAS libraries for its own matrix calculation routines. The version of MATLAB I have is a little dated (7.0.1), but nevertheless it would be interesting to see how its performance compares with that of latest MKL’s. MATLAB 7 is single threaded, and given the same matrix size, it runs roughly three times slower than the fastest MKL routine listed above (per core).

    a = rand(i,i);
    b = rand(i,i);
    tic;
    c = a*b;
    t = toc

The following table shows the results I obtained by running the code listed above. The results are time in seconds. (note, S.TH means single threaded and M.TH means multi-threaded).

The following figure shows the results. Since uBLAS and single threaded matrix multiplications took significantly longer to compute, I did not include them in the figure below.

The following figure shows the same data but uses log-scale Y axis instead so that all the data can show up nicely. You can get a sense of various algorithms’ efficiencies here: