## Image frame assembly

Image frame assembly — Image frame assembly helpers

## Functions

void | fpi_do_movement_estimation ()
FpImage * | fpi_assemble_frames ()
FpImage * | fpi_assemble_lines ()

## Types and Values

struct | fpi_frame
struct | fpi_frame_asmbl_ctx
struct | fpi_line_asmbl_ctx

## Description

Those are the helpers to manipulate capture data from fingerprint readers into a uniform image that can be further processed. This is usually used by drivers for devices which have a small sensor and thus need to capture data in small stripes.

## Functions

### fpi_do_movement_estimation ()

    void
    fpi_do_movement_estimation (struct fpi_frame_asmbl_ctx *ctx,
                                GSList *stripes);

fpi_do_movement_estimation() estimates the movement between adjacent frames, populating `delta_x` and `delta_y` values for each fpi_frame.

This function is used for devices that don't do movement estimation in hardware. If hardware movement estimation is supported, the driver should populate `delta_x` and `delta_y` instead.

#### Parameters

ctx | fpi_frame_asmbl_ctx - frame assembling context |
stripes | a singly-linked list of fpi_frame |

### fpi_assemble_frames ()

    FpImage *
    fpi_assemble_frames (struct fpi_frame_asmbl_ctx *ctx,
                         GSList *stripes);

fpi_assemble_frames() assembles individual frames into a single image. It expects `delta_x` and `delta_y` of fpi_frame to be populated.

#### Parameters

ctx | fpi_frame_asmbl_ctx - frame assembling context |
stripes | linked list of fpi_frame |

#### Returns

a newly allocated fp_img.

### fpi_assemble_lines ()

    FpImage *
    fpi_assemble_lines (struct fpi_line_asmbl_ctx *ctx,
                        GSList *lines,
                        size_t num_lines);

fpi_assemble_lines assembles individual lines into a single image. It also rescales image to account variable swiping speed.

Note that `num_lines` might be shorter than the length of the list, if some lines should be skipped.

#### Parameters

ctx | fpi_frame_asmbl_ctx - frame assembling context |
lines | linked list of lines |
num_lines | number of items in `lines` to process |

#### Returns

a newly allocated fp_img.

## Types and Values

### struct fpi_frame

    struct fpi_frame {
      int           delta_x;
      int           delta_y;
      unsigned char data[0];
    };

fpi_frame is used to store frames for swipe sensors. Drivers should populate delta_x and delta_y if the device supports hardware movement estimation.

#### Members

int `delta_x`; | X offset of the frame |
int `delta_y`; | Y offset of the frame |
unsigned char `data`[0]; | bitmap |

### struct fpi_frame_asmbl_ctx

    struct fpi_frame_asmbl_ctx {
      unsigned int  frame_width;
      unsigned int  frame_height;
      unsigned int  image_width;
      unsigned char (*get_pixel)(struct fpi_frame_asmbl_ctx *ctx,
                                 struct fpi_frame           *frame,
                                 unsigned int                x,
                                 unsigned int                y);
    };

fpi_frame_asmbl_ctx is a structure holding the context for frame assembling routines.

Drivers should define their own fpi_frame_asmbl_ctx depending on hardware parameters of scanner. `image_width` is usually 25% wider than `frame_width` to take horizontal movement into account.

#### Members

unsigned int `frame_width`; | width of the frame |
unsigned int `frame_height`; | height of the frame |
unsigned int `image_width`; | resulting image width |
`get_pixel` () | pixel accessor, returns pixel brightness at x,y of frame |

### struct fpi_line_asmbl_ctx

    struct fpi_line_asmbl_ctx {
      unsigned int line_width;
      unsigned int max_height;
      unsigned int resolution;
      unsigned int median_filter_size;
      unsigned int max_search_offset;
      int          (*get_deviation)(struct fpi_line_asmbl_ctx *ctx,
                                    GSList                    *line1,
                                    GSList                    *line2);
      unsigned char (*get_pixel)(struct fpi_line_asmbl_ctx *ctx,
                                 GSList                    *line,
                                 unsigned int               x);
    };

fpi_line_asmbl_ctx is a structure holding the context for line assembling routines.

Drivers should define their own fpi_line_asmbl_ctx depending on the hardware parameters of the scanner. Swipe scanners of this type usually return two lines, the second line is often narrower than first and is used for movement estimation.

The `max_search_offset` value indicates how many lines forward the assembling routines should look while searching for next line. This value depends on how fast the hardware sends frames.

The function pointed to by `get_deviation` should return the numerical difference between two lines. Higher values means lines are more different. If the reader returns two lines at a time, this function should be used to estimate the difference between pairs of lines.

#### Members

unsigned int `line_width`; | width of line |
unsigned int `max_height`; | maximal height of assembled image |
unsigned int `resolution`; | scale factor used for line assembling routines. |
unsigned int `median_filter_size`; | size of median filter for movement estimation |
unsigned int `max_search_offset`; | the number of lines to search for the next line |
`get_deviation` () | pointer to a function that returns the numerical difference between two lines |
`get_pixel` () | pixel accessor, returns pixel brightness at x of line |