Implements read_image and write_image functions. More...

Detailed Description

Implements read_image and write_image functions.

Author: Pascal Getreuer getre.nosp@m.uer@.nosp@m.cmla..nosp@m.ens-.nosp@m.cacha.nosp@m.n.fr

Two high-level functions are provided, read_image() and write_image(), for reading and writing image BMP, JPEG, PNG, and TIFF files. The desired format of the image data can be specified to read_image for how to return the data (and similarly to write_image for how it should interpret the data). Formatting options allow specifying the datatype of the components, conversion to grayscale, channel ordering, interleaved vs. planar, and row-major vs. column-major.

read_image automatically detects the format of the image being read so that the format does not need to be supplied explicitly. write_image infers the file format from the file extension.

Also included is a function identify_image_type() to guess the file type (BMP, JPEG, PNG, TIFF, and a few other formats) from the file header's magic numbers without reading the image.

Support for BMP reading and writing is native: BMP reading supports 1-, 2-, 4-, 8-, 16-, 32-bit uncompressed, RLE, and bitfield images; BMP writing is limited to 8- and 24-bit uncompressed. The implementation calls libjpeg, libpng, and libtiff to handle JPEG, PNG, and TIFF images.

This program is free software: you can redistribute it and/or modify it under, at your option, the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version, or the terms of the simplified BSD license.

You should have received a copy of these licenses along this program. If not, see http://www.gnu.org/licenses/ and http://www.opensource.org/licenses/bsd-license.html.

Definition in file imageio.c.

#include "imageio.h"
#include <string.h>
#include <ctype.h>

Go to the source code of this file.

Macros
#define	FILE_BUFFER_CAPACITY (1024*4)
	buffer size to use for BMP file I/O

#define	ROUNDCLAMPF(x)

#define	ROUNDCLAMP(x)

Functions
static int	string_ends_with (const char string, const char suffix)
	Case-insensitive test to see if string ends with suffix.

static void	fill_image (uint32_t *image, int width, int height, uint32_t color)
	Fill an image with a color.

static uint32_t *	get_image_palette (int num_colors, int use_color, int use_alpha, const uint32_t image, int width, int height)
	Check use of color and alpha, and count number of distinct colors. More...

static uint16_t	read_u16_le (FILE *file)
	Read a 16-bit little Endian word from file.

static uint32_t	read_u32_le (FILE *file)
	Read a 32-bit little Endian double word from file.

static void	write_u16_le (uint16_t w, FILE *file)
	Write a 16-bit word in little Endian format.

static void	write_u32_le (uint32_t dw, FILE *file)
	Write a 32-bit double word in little Endian format.

static int	read_bmp_1bpp (uint32_t image, int width, int height, FILE file, const uint32_t *palette)
	Internal function for reading 1-bpp BMP.

static int	read_bmp_4bpp (uint32_t image, int width, int height, FILE file, const uint32_t *palette)
	Internal function for reading 4-bpp BMP.

static int	read_bmp_4bpp_rle (uint32_t image, int width, int height, FILE file, const uint32_t *palette)
	Internal function for reading 4-bpp RLE-compressed BMP.

static int	read_bmp_8bpp (uint32_t image, int width, int height, FILE file, const uint32_t *palette)
	Internal function for reading 8-bpp BMP.

static int	read_bmp_8bpp_rle (uint32_t image, int width, int height, FILE file, const uint32_t *palette)
	Internal function for reading 8-bpp RLE-compressed BMP.

static int	read_bmp_24bpp (uint32_t image, int width, int height, FILE file)
	Internal function for reading 24-bpp BMP.

static void	get_mask_shifts (uint32_t mask, int left_shift, int right_shift)
	Internal function for determining bit shifts in bitfield BMP.

static int	read_bmp_16bpp (uint32_t image, int width, int height, FILE file, uint32_t redmask, uint32_t greenmask, uint32_t bluemask, uint32_t alphamask)
	Internal function for reading 16-bpp BMP.

static int	read_bmp_32bpp (uint32_t image, int width, int height, FILE file, uint32_t redmask, uint32_t greenmask, uint32_t bluemask, uint32_t alphamask)
	Internal function for reading 32-bpp BMP.

static int	read_bmp (uint32_t *image, int width, int height, FILE file)
	Read a BMP (Windows Bitmap) image file as RGBA data. More...

static int	write_bmp (const uint32_t image, int width, int height, FILE file)
	Write a BMP image. More...

static void *	convert_to_format (uint32_t *src, int width, int height, unsigned format)
	Convert from RGBA U8 to a specified format.

static uint32_t *	convert_from_format (void *src, int width, int height, unsigned format)
	Convert from a specified format to RGBA U8.

int	identify_image_type (char type, const char filename)
	Identify the file type of an image file by its magic numbers. More...

void *	read_image (int width, int height, const char *filename, unsigned format)
	Read an image file as 32-bit RGBA data. More...

int	write_image (void image, int width, int height, const char filename, unsigned format, int quality)
	Write an image file from 8-bit RGBA image data. More...

Macro Definition Documentation

#define ROUNDCLAMP ( x )

Value:

((x < 0.0) ? 0 : \

((x > 1.0) ? 255 : (uint8_t)(255.0*(x) + 0.5)))

Definition at line 66 of file imageio.c.

#define ROUNDCLAMPF ( x )

Value:

((x < 0.0f) ? 0 : \

((x > 1.0f) ? 255 : (uint8_t)(255.0f*(x) + 0.5f)))

Definition at line 64 of file imageio.c.

Function Documentation

static uint32_t* get_image_palette	(	int *	num_colors,
		int *	use_color,
		int *	use_alpha,
		const uint32_t *	image,
		int	width,
		int	height
	)

static

Check use of color and alpha, and count number of distinct colors.

Parameters

num_colors	set by the routine to the number of unique colors
use_color	set to 1 if the image is not grayscale
use_alpha	set to 1 if the image alpha is not constant 255
image	pointer to U8 RGBA interleaved image data
width,height	dimensions of the image

Returns: pointer to a color palette with num_colors entries or NULL if the number of distinct colors exceeds 256.

This routine checks whether an RGBA image makes use of color and alpha, and constructs a palette if the number of distinct colors is 256 or fewer. This information is useful for writing image files with smaller file size.

Definition at line 115 of file imageio.c.

int identify_image_type	(	char *	type,
		const char *	filename
	)

Identify the file type of an image file by its magic numbers.

Parameters

type	destination buffer with space for at least 5 chars
filename	image file name

Returns: 1 on successful identification, 0 on failure.

The routine fills type with an identifying string. If there is an error or the file type is unknown, type is set to a null string.

Definition at line 1955 of file imageio.c.

static int read_bmp	(	uint32_t **	image,
		int *	width,
		int *	height,
		FILE *	file
	)

static

Read a BMP (Windows Bitmap) image file as RGBA data.

Parameters

image,width,height	pointers to be filled with the pointer to the image data and the image dimensions.
file	stdio FILE pointer pointing to the beginning of the BMP file

Returns: 1 on success, 0 on failure

This function is called by read_image to read BMP images. Before calling read_bmp, the caller should open file as a FILE pointer in binary read mode. When read_bmp is complete, the caller should close file.

Definition at line 650 of file imageio.c.

void* read_image	(	int *	width,
		int *	height,
		const char *	filename,
		unsigned	format
	)

Read an image file as 32-bit RGBA data.

Parameters

width,height	pointers to be filled with the image dimensions
filename	image file name
format	specifies the desired format for the image

Returns: Pointer to the image data, or null on failure

The calling syntax is that the filename is the input and width, and height and the returned pointer are outputs. read_image allocates memory for the image as one contiguous block of memory and returns a pointer. It is the responsibility of the caller to call free on this pointer when done to release this memory.

A non-null pointer indicates success. On failure, the returned pointer is null, and width and height are set to 0.

The format argument is used by specifying one of the data type options

IMAGEIO_U8: unsigned 8-bit components
IMAGEIO_SINGLE: float components
IMAGEIO_DOUBLE: double components

and one of the channel options

IMAGEIO_GRAYSCALE: grayscale data
IMAGEIO_RGB: RGB color data (red is the first channel)
IMAGEIO_BGR: BGR color data (blue is the first channel)
IMAGEIO_RGBA: RGBA color+alpha data
IMAGEIO_BGRA: BGRA color+alpha data
IMAGEIO_ARGB: ARGB color+alpha data
IMAGEIO_ABGR: ABGR color+alpha data

and optionally either or both of the ordering options

IMAGEIO_PLANAR: planar order instead of interleaved components
IMAGEIO_COLUMNMAJOR: column major order instead of row major order

uint32_t *image;
int width, height;
if (!(image = (uint32_t *)read_image(&width, &height, "myimage.bmp",
    IMAGEIO_U8 | IMAGEIO_RGBA)))
    return 0;
printf("Read image of size %dx%d\n", width, height);
...
free(image);

With the default formatting IMAGEIO_U8 | IMAGEIO_RGBA, the image is organized in standard row major top-down 32-bit RGBA order. The image is organized as

    (Top left)                                             (Top right)
    image[0]                image[1]        ...  image[width-1]
    image[width]            image[width+1]  ...  image[2*width]
    ...                     ...             ...  ...
    image[width*(height-1)] ...             ...  image[width*height-1]
    (Bottom left)                                       (Bottom right)

Each element image[k] represents one RGBA pixel, which is a 32-bit bitfield. The components of pixel image[k] can be unpacked as

uint8_t *Component = (uint8_t *)&image[k];
uint8_t red = Component[0];
uint8_t green = Component[1];
uint8_t blue = Component[2];
uint8_t alpha = Component[3];

Each component is an unsigned 8-bit integer value with range 0-255. Most images do not have alpha information, in which case the alpha component is set to value 255 (full opacity).

With IMAGEIO_SINGLE or IMAGEIO_DOUBLE, the components are values in the range 0 to 1.

Definition at line 2083 of file imageio.c.

static int write_bmp	(	const uint32_t *	image,
		int	width,
		int	height,
		FILE *	file
	)

static

Write a BMP image.

Parameters

image	pointer to RGBA image data
width,height	the image dimensions
file	stdio FILE pointer

Returns: 1 on success, 0 on failure

This function is called by write_image to write BMP images. The caller should open file in binary write mode. When write_bmp is complete, the caller should close file.

The image is generally saved in uncompressed 24-bit RGB format. But where possible, the image is saved using an 8-bit palette for a substantial decrease in file size. The image data is always saved losslessly.

Note: The alpha channel is lost when saving to BMP. It is possible to write the alpha channel in a 32-bit BMP image, however, such images are not widely supported. RGB 24-bit BMP on the other hand is well supported.

Definition at line 853 of file imageio.c.

int write_image	(	void *	image,
		int	width,
		int	height,
		const char *	filename,
		unsigned	format,
		int	quality
	)

Write an image file from 8-bit RGBA image data.

Parameters

image	pointer to the image data
width,height	image dimensions
filename	image file name
format	specifies how the data is formatted (see read_image)
quality	the JPEG image quality (between 0 and 100)

Returns: 1 on success, 0 on failure

The input image should be a 32-bit RGBA image stored as in the description of read_image. write_image writes to filename in the file format specified by its extension. If saving a JPEG image, the quality argument specifies the quality factor (between 0 and 100). quality has no effect on other formats.

The return value indicates success with 1 or failure with 0.

Definition at line 2188 of file imageio.c.

Detailed Description

Macros

Functions

Macro Definition Documentation

Function Documentation