Image operations: libfprint Reference Manual

## Image operations Image operations — Image operation functions |

## Functions

void | fp_img_free ()
int | fp_img_get_height ()
int | fp_img_get_width ()
unsigned char * | fp_img_get_data ()
int | fp_img_save_to_file ()
void | fp_img_standardize ()
struct fp_img * | fp_img_binarize ()
struct fp_minutia ** | fp_img_get_minutiae ()
int | fp_minutia_get_coords ()

## Types and Values

struct | fp_img
struct | fp_minutia

## Includes

    #include <fprint.h>

## Description

libfprint offers several ways of retrieving images from imaging devices, one example being the `fp_dev_img_capture()` function. The functions documented below allow you to work with such images.

### Image format

All images are represented as 8-bit greyscale data.

### Image standardization

In some contexts, images you are provided through libfprint are raw images from the hardware. The orientation of these varies from device-to-device, as does the color scheme (black-on-white or white-on-black?). libfprint provides the `fp_img_standardize()` function to convert images into standard form, which is defined to be: finger flesh as black on white surroundings, natural upright orientation.

## Functions

### fp_img_free ()

    void
    fp_img_free (struct fp_img *img);

Frees an image. Must be called when you are finished working with an image.

#### Parameters

img | the image to destroy. If `NULL`, function simply returns. |

### fp_img_get_height ()

    int
    fp_img_get_height (struct fp_img *img);

Gets the pixel height of an image.

#### Parameters

img | an image |

#### Returns

the height of the image

### fp_img_get_width ()

    int
    fp_img_get_width (struct fp_img *img);

Gets the pixel width of an image.

#### Parameters

img | an image |

#### Returns

the width of the image

### fp_img_get_data ()

    unsigned char *
    fp_img_get_data (struct fp_img *img);

Gets the greyscale data for an image. This data must not be modified or freed, and must not be used after `fp_img_free()` has been called.

#### Parameters

img | an image |

#### Returns

a pointer to libfprint's internal data for the image

### fp_img_save_to_file ()

    int
    fp_img_save_to_file (struct fp_img *img,
                         char *path);

A quick convenience function to save an image to a file in PGM format.

#### Parameters

img | the image to save |
path | the path to save the image. Existing files will be overwritten. |

#### Returns

0 on success, non-zero on error.

### fp_img_standardize ()

    void
    fp_img_standardize (struct fp_img *img);

Standardizes an image by normalizing its orientation, colors, etc. It is safe to call this multiple times on an image, libfprint keeps track of the work it needs to do to make an image standard and will not perform these operations more than once for a given image.

#### Parameters

img | the image to standardize |

### fp_img_binarize ()

    struct fp_img *
    fp_img_binarize (struct fp_img *img);

Get a binarized form of a standardized scanned image. This is where the fingerprint image has been "enhanced" and is a set of pure black ridges on a pure white background. Internally, image processing happens on top of the binarized image.

The image must have been standardized otherwise this function will fail.

It is safe to binarize an image and free the original while continuing to use the binarized version.

You cannot binarize an image twice.

#### Parameters

img | a standardized image |

#### Returns

a new image representing the binarized form of the original, or `NULL` on error. Must be freed with `fp_img_free()` after use.

### fp_img_get_minutiae ()

    struct fp_minutia **
    fp_img_get_minutiae (struct fp_img *img,
                         int *nr_minutiae);

Get a list of minutiae detected in an image. A minutia point is a feature detected on a fingerprint, typically where ridges end or split. libfprint's image processing code relies upon comparing sets of minutiae, so accurate placement of minutia points is critical for good imaging performance.

The image must have been standardized otherwise this function will fail.

You cannot pass a binarized image to this function. Instead, pass the original image.

Returns a list of pointers to minutiae, where the list is of length indicated in the nr_minutiae output parameter. The returned list is only valid while the parent image has not been freed, and the minutiae data must not be modified or freed.

#### Parameters

img | a standardized image |
nr_minutiae | an output location to store minutiae list length |

#### Returns

a list of minutiae points. Must not be modified or freed.

### fp_minutia_get_coords ()

    int
    fp_minutia_get_coords (struct fp_minutia *minutia,
                           int *coord_x,
                           int *coord_y);

Sets `coord_x` and `coord_y` to be the coordinates of the detected minutia, so it can be presented in a more verbose user interface. This is usually only used for debugging purposes.

#### Parameters

minutia | a struct fp_minutia |
coord_x | the return variable for the X coordinate of the minutia |
coord_y | the return variable for the Y coordinate of the minutia |

#### Returns

0 on success, -1 on error.

## Types and Values

### struct fp_img

    struct fp_img {
    	int width;
    	int height;
    	size_t length;
    	FpiImgFlags flags;
    	unsigned char *binarized;
    	unsigned char data[0];
    };

fp_img is an opaque structure type. You must access it using the functions in this section.

### struct fp_minutia

    struct fp_minutia;

fp_minutia is an opaque structure type. You must access it using the functions in this section.