Documentation>C API
Data Structures
pgm.h File Reference

Portable graymap format (PGM) parser. More...

`#include "generic.h"`
`#include "mathop.h"`
`#include <stdio.h>`

## Data Structures

struct | VlPgmImage
| PGM image meta data. More...

## Macros

PGM parser error codes
#define | VL_ERR_PGM_INV_HEAD 101
#define | VL_ERR_PGM_INV_META 102
#define | VL_ERR_PGM_INV_DATA 103
#define | VL_ERR_PGM_IO 104

## Functions

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

## Detailed Description

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

Extracting an image encoded in PGM format from an imput file stream involves the following steps:

- use vl_pgm_extract_head to extract the image meta data (size and bit depth);
- allocate a buffer to store the image data;
- use vl_pgm_extract_data to extract the image data to the allocated buffer.

Writing an image in PGM format to an ouptut file stream can be done by using 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

## Macro Definition Documentation

## ◆ VL_ERR_PGM_INV_DATA

#define VL_ERR_PGM_INV_DATA 103

Invalid PGM data section.

## ◆ VL_ERR_PGM_INV_HEAD

#define VL_ERR_PGM_INV_HEAD 101

Invalid PGM header section.

## ◆ VL_ERR_PGM_INV_META

#define VL_ERR_PGM_INV_META 102

Invalid PGM meta section.

## ◆ VL_ERR_PGM_IO

#define VL_ERR_PGM_IO 104

Generic I/O error.

## Function Documentation

## ◆ vl_pgm_extract_data()

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.

Returns
  error code.

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.

## ◆ vl_pgm_extract_head()

int vl_pgm_extract_head | ( | FILE * | f,
|  | VlPgmImage * | im )

Parameters

  f | input file.
  im | image structure to fill.

Returns
  error code.

The function extracts from the file f the meta-data section of an image encoded in PGM format. The function fills the structure VlPgmImage accordingly.

The error may be either VL_ERR_PGM_INV_HEAD or VL_ERR_PGM_INV_META depending whether the error occurred in decoding the header or meta section of the PGM file.

## ◆ vl_pgm_get_bpp()

vl_size vl_pgm_get_bpp | ( | VlPgmImage const * | im | ) |

Parameters

  im | PGM image descriptor.

Returns
  number of bytes per pixel.

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

## ◆ vl_pgm_get_npixels()

vl_size vl_pgm_get_npixels | ( | VlPgmImage const * | im | ) |

Parameters

  im | PGM image descriptor.

Returns
  number of pixels of the image.

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()).

## ◆ vl_pgm_insert()

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.

## ◆ vl_pgm_read_new()

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.

Returns
  error code.

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.

## ◆ vl_pgm_read_new_f()

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.

Returns
  error code.

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.

## ◆ vl_pgm_write()

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.

Returns
  error code.

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().

## ◆ vl_pgm_write_f()

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.

Returns
  error code.

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().