C API

pgm.h File Reference


Detailed Description

This module implements basic input and ouptut of images in PGM format.

To extract a PGM image from an input stream, first call vl_pgm_extract_head() to extract the image meta data (size and bit-depth). Then allocate the appropriate buffer to hold the image pixels and then call vl_pgm_extract_data().

To insert a PGM image to a file stream use vl_pgm_insert().

To quickly read/write a PGM image from/to a given file, use vl_pgm_read_new() and vl_pgm_write(). To to the same from a buffer in floating point format use vl_pgm_read_new_f() and vl_pgm_write_f().

Author:
Andrea Vedaldi

Definition in file pgm.h.

#include "generic.h"
#include "mathop.h"

Go to the source code of this file.


Data Structures

struct  _VlPgmImage
 PGM image meta data. More...

Typedefs

typedef struct _VlPgmImage VlPgmImage
 PGM image meta data type.

Functions

Core operations
VL_EXPORT int vl_pgm_extract_head (FILE *f, VlPgmImage *im)
 Extract PGM header from stream.
VL_EXPORT int vl_pgm_extract_data (FILE *f, VlPgmImage const *im, void *data)
 Extract PGM data from stream.
VL_EXPORT int vl_pgm_insert (FILE *f, VlPgmImage const *im, void const *data)
 Insert a PGM image into a stream.
VL_EXPORT int vl_pgm_get_npixels (VlPgmImage const *im)
 Get PGM image number of pixels.
VL_EXPORT int vl_pgm_get_bpp (VlPgmImage const *im)
 Get PGM image bytes per pixel.
Helper functions
VL_EXPORT int vl_pgm_write (char const *name, vl_uint8 const *data, int width, int height)
 Write bytes to a PGM file.
VL_EXPORT int vl_pgm_write_f (char const *name, float const *data, int width, int height)
 Write floats to PGM file.
VL_EXPORT int vl_pgm_read_new (char const *name, VlPgmImage *im, vl_uint8 **data)
 Read a PGM file.
VL_EXPORT int vl_pgm_read_new_f (char const *name, VlPgmImage *im, float **data)
 Read floats from a PGM file.

Typedef Documentation

typedef struct _VlPgmImage VlPgmImage

See also:
_VlPgmImage.

Definition at line 46 of file pgm.h.


Function Documentation

VL_EXPORT int vl_pgm_extract_data ( FILE *  f,
VlPgmImage const *  im,
void *  data 
)

Parameters:
f input file.
im PGM image descriptor.
data data buffer to fill.
The function extracts from the file f the data section of an image encoded in PGM format. The function fills the buffer data according. The buffer data should be vl_pgm_get_npixels() by vl_pgm_get_bpp() bytes large.

Returns:
error code.

Definition at line 274 of file pgm.c.

References _VlPgmImage::is_raw, vl_err_msg, VL_ERR_MSG_LEN, vl_err_no, vl_pgm_get_bpp(), and vl_pgm_get_npixels().

Referenced by vl_pgm_read_new().

VL_EXPORT int vl_pgm_extract_head ( FILE *  f,
VlPgmImage im 
)

Parameters:
f input file.
im image structure to fill.
The function extracts from the file f the meta-data section of an image encoded in PGM format. The function fills the structure VlPgmImage according.

Returns:
error code. The function sets vl_err_no to VL_PGM_INV_HEAD or VL_PGM_INV_META depending whether the error occurred in decoding the header or meta section of the PGM file.

Definition at line 165 of file pgm.c.

References remove_blanks(), and vl_err_no.

Referenced by vl_pgm_read_new().

VL_EXPORT int vl_pgm_get_bpp ( VlPgmImage const *  im  ) 

Parameters:
im PGM image descriptor.
The function returns the number of bytes for each pixel of the PGM image im.

Returns:
number of bytes per pixel.

Definition at line 143 of file pgm.c.

References _VlPgmImage::max_value.

Referenced by vl_pgm_extract_data(), vl_pgm_insert(), and vl_pgm_read_new().

VL_EXPORT int vl_pgm_get_npixels ( VlPgmImage const *  im  ) 

Parameters:
im PGM image descriptor.
The functions returns the number of pixels of the PGM image im.

To calculate the image data size in bytes, this value must be multiplied by the number of byte per pixels (see vl_pgm_get_bpp()).

Returns:
number of pixels of the image.

Definition at line 125 of file pgm.c.

References _VlPgmImage::height, and _VlPgmImage::width.

Referenced by vl_pgm_extract_data(), vl_pgm_insert(), vl_pgm_read_new(), and vl_pgm_read_new_f().

VL_EXPORT int vl_pgm_insert ( FILE *  f,
VlPgmImage const *  im,
void const *  data 
)

Parameters:
f output file.
im PGM image meta-data.
data image data.
Returns:
error code.

Definition at line 352 of file pgm.c.

References _VlPgmImage::height, _VlPgmImage::max_value, vl_err_msg, VL_ERR_MSG_LEN, vl_err_no, vl_free(), vl_malloc(), vl_pgm_get_bpp(), vl_pgm_get_npixels(), and _VlPgmImage::width.

Referenced by vl_pgm_write().

VL_EXPORT int vl_pgm_read_new ( char const *  name,
VlPgmImage im,
vl_uint8 **  data 
)

Parameters:
name file name.
im a pointer to the PGM image structure to fill.
data a pointer to the pointer to the allocated buffer.
The function reads a PGM image from file name and initializes the structure im and the buffer data accordingly.

The ownership of the buffer data is transfered to the caller. data should be freed by means of vl_free().

Bug:
Only PGM files with 1 BPP are supported.
Returns:
error code.

Definition at line 414 of file pgm.c.

References VL_ERR_BAD_ARG, vl_err_msg, VL_ERR_MSG_LEN, vl_err_no, vl_free(), vl_malloc(), vl_pgm_extract_data(), vl_pgm_extract_head(), vl_pgm_get_bpp(), and vl_pgm_get_npixels().

Referenced by vl_pgm_read_new_f().

VL_EXPORT int vl_pgm_read_new_f ( char const *  name,
VlPgmImage im,
float **  data 
)

Parameters:
name file name.
im a pointer to the PGM image structure to fill.
data a pointer to the pointer to the allocated buffer.
The function reads a PGM image from file name and initializes the structure im and the buffer data accordingly. The buffer data is an array of floats in the range [0, 1].

The ownership of the buffer data is transfered to the caller. data should be freed by means of vl_free().

Bug:
Only PGM files with 1 BPP are supported.
Returns:
error code.

Definition at line 472 of file pgm.c.

References _VlPgmImage::max_value, vl_free(), vl_malloc(), vl_pgm_get_npixels(), and vl_pgm_read_new().

VL_EXPORT int vl_pgm_write ( char const *  name,
vl_uint8 const *  data,
int  width,
int  height 
)

Parameters:
name file name.
data data to write.
width width of the image.
height height of the image.
The function dumps the image data to the PGM file of the specified name. This is an helper function simplifying the usage of vl_pgm_insert().

Returns:
error code.

Definition at line 511 of file pgm.c.

References _VlPgmImage::height, _VlPgmImage::is_raw, _VlPgmImage::max_value, vl_err_msg, VL_ERR_MSG_LEN, vl_err_no, vl_pgm_insert(), and _VlPgmImage::width.

Referenced by vl_pgm_write_f().

VL_EXPORT int vl_pgm_write_f ( char const *  name,
float const *  data,
int  width,
int  height 
)

Parameters:
name file name.
data data to write.
width width of the image.
height height of the image.
The function dumps the image data to the PGM file of the specified name. The data is re-scaled to fit in the range 0-255. This is an helper function simplifying the usage of vl_pgm_insert().

Returns:
error code.

Definition at line 553 of file pgm.c.

References VL_EPSILON_F, vl_free(), VL_INFINITY_F, vl_malloc(), VL_MAX, VL_MIN, and vl_pgm_write().