NAME

kjb_read_image - Reads an image into the kjb image structure

SYNOPSIS

#include "i/i_float_io.h"

Example compile flags (system dependent):
  -DLINUX_X86_64 -DLINUX_X86_64_OPTERON  -DGNU_COMPILER 
   -I/home/kobus/include
   -L/home/kobus/misc/load/linux_x86_64_opteron -L/usr/lib/x86_64-linux-gnu
  -lKJB                               -lfftw3  -lgsl -lgslcblas -ljpeg  -lSVM -lstdc++                    -lpthread -lSLATEC -lg2c    -lacml -lacml_mv -lblas -lg2c      -lncursesw 


int kjb_read_image
(
	KJB_image **ipp,
	const char *file_name_gz_and_sub_image
);

DESCRIPTION

This routine reads an image from a file into the kjb image structure which is a floating point precession RGB format. It also does pre-processing under the control of options which have normally been set through calls to process_kjb_options(3) or kjb_set(3), normally with user input, but sometimes with hard coded constant strings. For reading without pre-processing, see kjb_read_image_2. This routine natively reads sun-raster, simple jpeg, simple tiff, and the home grown floating point formats kiff, and mid. In addition, it will arrange conversion from most other 24-bit formats, provided that a conversion program is available. Currently the pre-processing (optionally) done includes offset removal, linearization, removing fixed pattern noise, correcting for fixed gradients due to optics, bloom removal, striping of images exactly the videograbber size, striping images by a specifiied amount, marking clipped pixels as invald, and marking dark pixels as invalid. It is dangerous to rely on defaults of these behaviours, but currently the default is to remove the offset only if the required configuration files are in place, NOT to remove bloom, NOT to strip videograbber size images, to mark clipped pixels (ones that are 255 or greater) EVEN in the case of float kiff as explained below, and to mark dark pixels. Float kiff images store validity information as well as pixel values. By default, this stored validity information is used instead the validity being recomputed based on the clip point and dark pixel levels. To obtain the equally useful alternate behaviour, whereby the validity information is recomputed, use the fs_reset_invalid_pixels option (rip=t).

RETURNS

NO_ERROR on sucess and ERROR on failure, with an error message being set.

WARNING

It is dangerous to rely on defaults. They change, and it is hard to keep documentation in sync. If it makes a difference to the application, it is best to set the options formally.

WARNING

The fancy nature of this routine has caused confusion. It is quite useful, but often starting with kjb_read_image_2 is better. However, if this routine can be used to manipulate images on read under user control which has a lot of advantages in some cirumstances.

DISCLAIMER

This software is not adequatedly tested. It is recomended that results are checked independantly where appropriate.

AUTHOR

Kobus Barnard

DOCUMENTER

Kobus Barnard

SEE ALSO

kjb_read_image_2 , kjb_write_image , display_matrix , kjb_display_image