Some standard conversion functions. More...

#include <vcl_cassert.h>
#include <vcl_limits.h>
#include <vil/vil_transform.h>
#include <vil/vil_math.h>
#include <vil/vil_plane.h>
#include <vil/vil_copy.h>
#include <vil/vil_exception.h>

Classes
class	vil_convert_cast_pixel< In, Out >
	Performs conversion between different pixel types. More...
class	vil_convert_round_pixel< In, Out >
	Performs rounding between different pixel types. More...
class	vil_convert_rgb_to_grey_pixel< inP, outP >
	Convert various rgb types to greyscale, using given weights. More...
Functions
template<class inP , class outP >
void	vil_convert_cast (const vil_image_view< inP > &src, vil_image_view< outP > &dest)
	Cast one pixel type to another.
template<class inP , class outP >
void	vil_convert_round (const vil_image_view< inP > &src, vil_image_view< outP > &dest)
	Convert one pixel type to another with rounding.
template<class rgbP , class outP >
void	vil_convert_rgb_to_grey (const vil_image_view< rgbP > &src, vil_image_view< outP > &dest, double rw=0.2125, double gw=0.7154, double bw=0.0721)
	Convert single plane rgb (or rgba) images to greyscale.
template<class inP , class outP >
void	vil_convert_planes_to_grey (const vil_image_view< inP > &src, vil_image_view< outP > &dest, double rw=0.2125, double gw=0.7154, double bw=0.0721)
	Convert first three planes of src image to grey, assuming rgb.
template<class T >
void	vil_convert_stretch_range (const vil_image_view< T > &src, vil_image_view< vxl_byte > &dest)
	Convert src to byte image dest by stretching to range [0,255].
template<class inP >
void	vil_convert_stretch_range (const vil_image_view< inP > &src, vil_image_view< double > &dest, double lo, double hi)
	Convert src to double image dest by stretching to range [lo,hi].
template<class inP >
void	vil_convert_stretch_range (const vil_image_view< inP > &src, vil_image_view< float > &dest, float lo, float hi)
	Convert src to float image dest by stretching to range [lo,hi].
template<class inP >
void	vil_convert_stretch_range_limited (const vil_image_view< inP > &src, vil_image_view< double > &dest, const inP src_lo, const inP src_hi, const double dest_lo, const double dest_hi)
	Convert src image<inP> to dest image<double> by stretching input range [src_lo, src_hi] to output range [dest_lo, dest_hi].
template<class inP >
void	vil_convert_stretch_range_limited (const vil_image_view< inP > &src, vil_image_view< float > &dest, const inP src_lo, const inP src_hi, const float dest_lo, const float dest_hi)
	Convert src image<inP> to dest image<float> by stretching input range [src_lo, src_hi] to output range [dest_lo, dest_hi].
template<class inP >
void	vil_convert_stretch_range_limited (const vil_image_view< inP > &src, vil_image_view< unsigned short > &dest, const inP src_lo, const inP src_hi, const unsigned short dest_lo, const unsigned short dest_hi)
	Convert src image<inP> to dest image<ushort> by stretching input range [src_lo, src_hi] to output range [dest_lo, dest_hi].
template<class inP >
void	vil_convert_stretch_range_limited (const vil_image_view< inP > &src, vil_image_view< vxl_byte > &dest, const inP src_lo, const inP src_hi, const vxl_byte dest_lo, const vxl_byte dest_hi)
	Convert src image<inP> to dest image<ubyte> by stretching input range [src_lo, src_hi] to output range [dest_lo, dest_hi].
template<class inP >
void	vil_convert_stretch_range_limited (const vil_image_view< inP > &src, vil_image_view< vxl_byte > &dest, const inP src_lo, const inP src_hi)
	Convert src image<inP> to dest image<vxl_byte> by stretching input range [src_lo, src_hi] to output range [0, 255].
template<class outP >
vil_image_view_base_sptr	vil_convert_cast (outP, const vil_image_view_base_sptr &src)
	Cast the unknown pixel type to the known one.
template<class outP >
vil_image_view_base_sptr	vil_convert_round (outP, const vil_image_view_base_sptr &src)
	Convert an image of any pixel type to another with rounding.
vil_image_view_base_sptr	vil_convert_to_component_order (const vil_image_view_base_sptr &src)
	Force data to be suitable for viewing as multi component view.
vil_image_view_base_sptr	vil_convert_to_grey_using_average (const vil_image_view_base_sptr &src)
	Create a greyscale image of specified pixel type from any image src.
vil_image_view_base_sptr	vil_convert_to_grey_using_rgb_weighting (double rw, double gw, double bw, const vil_image_view_base_sptr &src)
	Create a greyscale image from any image src.
vil_image_view_base_sptr	vil_convert_to_grey_using_rgb_weighting (const vil_image_view_base_sptr &src)
	Create a greyscale image from any image src using default weights.
vil_image_view_base_sptr	vil_convert_to_n_planes (unsigned n_planes, const vil_image_view_base_sptr &src)
	Create an n plane image from any image src.
template<class outP >
vil_image_view_base_sptr	vil_convert_stretch_range (outP, const vil_image_view_base_sptr &src)
	Create an image of the desired type by stretching the range to fit.

Detailed Description

Some standard conversion functions.

Author:: Ian Scott.

This file contains a large number of image to image conversion functions. They are in two basic function types (plus a few helper functions.) Some involve only explicit types and convert a vil_image_view<T> to a vil_image_view<T>, the others take an unknown pixel type, using a vil_image_view_base_sptr. The basic conversion operations (e.g. casting, rounding) are available in both types. All of the conversions attempt to find shortcuts, so the output may be a reconfigured, or shallow copy of the input.

vil_convert with explicit pixel types

These are useful when you have two vil_image_view objects you want to convert between. You can use them in templates where the pixel type is one of the template parameters. These functions may create a shallow copy of the input if the types match to save unnecessary work.

vil_convert_cast
vil_convert_round
vil_convert_rgb_to_grey
vil_convert_planes_to_grey
vil_convert_stretch_range

vil_convert with unknown pixel types

These functions are useful when taking an image from vil_load or vil_image_resource::get_view(), where you may not know the pixel type in advance, but want to force the image into a particular pixel type.

vil_convert_cast
vil_convert_round
vil_convert_rgb_to_grey
vil_convert_planes_to_grey
vil_convert_stretch_range
vil_convert_to_component_order
vil_convert_to_n_planes

In general these functions expect to take scalar pixel images as inputs. Even though many of these functions could return a known pixel-typed image, they all return a vil_image_view_base_sptr, so that the functions can be strung along.

Note that these vil_convert_..( vil_image_view_base_sptr ) functions are provided as a convenience for users of vil_load and vil_image_resource::get_view(). Their existence should not suggest that it is sensible to use a vil_image_view_base_sptr as storage, nor that it is a good idea to write functions that take or return a vil_image_view_base_sptr. If you need a pixel-type-agnostic image container then use a vil_image_resource_sptr

It may be a good idea to provide vil_image_resource_sptr based vil_converts as well.

The ITK project (in Code/IO/itkConvertPixelBuffer.txx) has functionality similar to the RGB to grayscale conversion here. A change was made in ITK so the computation is (2125.0*r+7154.0*g+0721.0*b)/1000.0 instead of 0.2125*r+0.7154*g+0.0721*b. The reason is that the latter expression can produce different results between Intel and non-Intel platforms (even in cases where r==g && g==b), probably due to different floating point representations. This may not be too important, but it is worth noting here. In vil_convert.h we cannot make the same change without adding computation because vil_convert_rgb_to_grey() lets you pass in the weights. We'd have to multiply by 10000 to maintain the current API.

    Modifications
     23 Oct.2003 - Peter Vanroose - Added support for 64-bit int pixels
     30 Mar.2007 - Peter Vanroose - Commented out deprecated versions of vil_convert_cast & vil_convert_to_grey_using_average

Definition in file vil_convert.h.

Function Documentation

template<class inP , class outP >

void vil_convert_cast	(	const vil_image_view< inP > &	src,
		vil_image_view< outP > &	dest
	)		`[inline]`

Cast one pixel type to another.

There must be a cast operator from inP to outP

If the two pixel types are the same, the destination may only be a shallow copy of the source.

Definition at line 242 of file vil_convert.h.

template<class outP >

vil_image_view_base_sptr vil_convert_cast	(	outP	,
		const vil_image_view_base_sptr &	src
	)		`[inline]`

Cast the unknown pixel type to the known one.

This function is designed to be used with vil_load or vil_image_resource::get_view() where you do not know the pixel type in advance. If you need a multi-component view, then call this to get the corresponding multi-planar view, and do a second (cheap) conversion. The input image's storage arrangement may not be preserved.

Definition at line 706 of file vil_convert.h.

template<class inP , class outP >

void vil_convert_planes_to_grey	(	const vil_image_view< inP > &	src,
		vil_image_view< outP > &	dest,
		double	rw = `0.2125`,
		double	gw = `0.7154`,
		double	bw = `0.0721`
	)		`[inline]`

Convert first three planes of src image to grey, assuming rgb.

Pixel types can be different. Rounding will take place if appropriate.

Default weights convert from linear RGB to CIE luminance assuming a modern monitor. See Charles Poynton's Colour FAQ http://www.poynton.com/ColorFAQ.html

Definition at line 490 of file vil_convert.h.

template<class rgbP , class outP >

void vil_convert_rgb_to_grey	(	const vil_image_view< rgbP > &	src,
		vil_image_view< outP > &	dest,
		double	rw = `0.2125`,
		double	gw = `0.7154`,
		double	bw = `0.0721`
	)		`[inline]`

Convert single plane rgb (or rgba) images to greyscale.

Component types can be different. Rounding will take place if appropriate.

Default weights convert from linear RGB to CIE luminance assuming a modern monitor. See Charles Poynton's Colour FAQ http://www.poynton.com/ColorFAQ.html

Definition at line 472 of file vil_convert.h.

template<class inP , class outP >

void vil_convert_round	(	const vil_image_view< inP > &	src,
		vil_image_view< outP > &	dest
	)		`[inline]`

Convert one pixel type to another with rounding.

This should only be used to convert scalar pixel types to other scalar pixel types, or RGBs to RGBs. This function only rounds in terms of the destination type.

If the two pixel types are the same, the destination may only be a shallow copy of the source.

Definition at line 440 of file vil_convert.h.

template<class outP >

vil_image_view_base_sptr vil_convert_round	(	outP	,
		const vil_image_view_base_sptr &	src
	)		`[inline]`

Convert an image of any pixel type to another with rounding.

This should only be used to convert to scalar pixel types. This function only rounds in terms of the destination type. This function is designed to be used with vil_load or vil_image_resource::get_view() where you do not know the pixel type in advance.

If the input image already has outP as its pixel type, the destination may only be a shallow copy of the source. outP should be a scalar pixel type. The input image's storage arrangement may not be preserved.

Definition at line 805 of file vil_convert.h.

template<class T >

void vil_convert_stretch_range	(	const vil_image_view< T > &	src,
		vil_image_view< vxl_byte > &	dest
	)		`[inline]`

Convert src to byte image dest by stretching to range [0,255].

Definition at line 508 of file vil_convert.h.

template<class inP >

void vil_convert_stretch_range	(	const vil_image_view< inP > &	src,
		vil_image_view< double > &	dest,
		double	lo,
		double	hi
	)		`[inline]`

Convert src to double image dest by stretching to range [lo,hi].

Definition at line 533 of file vil_convert.h.

template<class inP >

void vil_convert_stretch_range	(	const vil_image_view< inP > &	src,
		vil_image_view< float > &	dest,
		float	lo,
		float	hi
	)		`[inline]`

Convert src to float image dest by stretching to range [lo,hi].

Definition at line 552 of file vil_convert.h.

template<class outP >

vil_image_view_base_sptr vil_convert_stretch_range	(	outP	,
		const vil_image_view_base_sptr &	src
	)		`[inline]`

Create an image of the desired type by stretching the range to fit.

This function is designed to be used with vil_load or vil_image_resource::get_view() where you do not know the pixel type in advance. In the case of floating point output pixels the range is set to [0,1] The input image's storage arrangement may not be preserved.

This function works on scalar pixel types only. You can convert the image to rgb using a cheap assignment afterwards.

Definition at line 1232 of file vil_convert.h.

template<class inP >

void vil_convert_stretch_range_limited	(	const vil_image_view< inP > &	src,
		vil_image_view< double > &	dest,
		const inP	src_lo,
		const inP	src_hi,
		const double	dest_lo,
		const double	dest_hi
	)		`[inline]`

Convert src image<inP> to dest image<double> by stretching input range [src_lo, src_hi] to output range [dest_lo, dest_hi].

Inputs < src_lo are mapped to dest_lo, and inputs > src_hi to dest_hi.

Definition at line 573 of file vil_convert.h.

template<class inP >

void vil_convert_stretch_range_limited	(	const vil_image_view< inP > &	src,
		vil_image_view< float > &	dest,
		const inP	src_lo,
		const inP	src_hi,
		const float	dest_lo,
		const float	dest_hi
	)		`[inline]`

Convert src image<inP> to dest image<float> by stretching input range [src_lo, src_hi] to output range [dest_lo, dest_hi].

Inputs < src_lo are mapped to dest_lo, and inputs > src_hi to dest_hi.

Definition at line 599 of file vil_convert.h.

template<class inP >

void vil_convert_stretch_range_limited	(	const vil_image_view< inP > &	src,
		vil_image_view< unsigned short > &	dest,
		const inP	src_lo,
		const inP	src_hi,
		const unsigned short	dest_lo,
		const unsigned short	dest_hi
	)		`[inline]`

Convert src image<inP> to dest image<ushort> by stretching input range [src_lo, src_hi] to output range [dest_lo, dest_hi].

Inputs < src_lo are mapped to dest_lo, and inputs > src_hi to dest_hi.

Definition at line 625 of file vil_convert.h.

template<class inP >

void vil_convert_stretch_range_limited	(	const vil_image_view< inP > &	src,
		vil_image_view< vxl_byte > &	dest,
		const inP	src_lo,
		const inP	src_hi,
		const vxl_byte	dest_lo,
		const vxl_byte	dest_hi
	)		`[inline]`

Convert src image<inP> to dest image<ubyte> by stretching input range [src_lo, src_hi] to output range [dest_lo, dest_hi].

Inputs < src_lo are mapped to dest_lo, and inputs > src_hi to dest_hi.

Definition at line 651 of file vil_convert.h.

template<class inP >

void vil_convert_stretch_range_limited	(	const vil_image_view< inP > &	src,
		vil_image_view< vxl_byte > &	dest,
		const inP	src_lo,
		const inP	src_hi
	)		`[inline]`

Convert src image<inP> to dest image<vxl_byte> by stretching input range [src_lo, src_hi] to output range [0, 255].

Inputs < src_lo are mapped to 0, and inputs > src_hi to 255.

Definition at line 677 of file vil_convert.h.

vil_image_view_base_sptr vil_convert_to_component_order ( const vil_image_view_base_sptr & src ) [inline]

Force data to be suitable for viewing as multi component view.

The output data will have values from different planes but the same pixel location stored in adjacent memory locations. After using this function on an input with 3 planes, an assignment to a vil_image_view<vil_rgb<T> > will always work. The input image's scalar pixel type will be preserved.

Definition at line 856 of file vil_convert.h.

vil_image_view_base_sptr vil_convert_to_grey_using_average ( const vil_image_view_base_sptr & src ) [inline]

Create a greyscale image of specified pixel type from any image src.

This function is designed to be used with vil_load or vil_image_resource::get_view() where you do not know the pixel type in advance. e.g.

 vil_image_view<float> input = vil_convert_cast(
   convert_to_grey_using_average(vil_load(filename)), float());

The output may be a reconfigured view of the input. The input image's pixel type and storage arrangement may not be preserved.

Definition at line 974 of file vil_convert.h.

vil_image_view_base_sptr vil_convert_to_grey_using_rgb_weighting	(	double	rw,
		double	gw,
		double	bw,
		const vil_image_view_base_sptr &	src
	)		`[inline]`

Create a greyscale image from any image src.

This function is designed to be used with vil_load or vil_image_resource::get_view() where you do not know the pixel type in advance. The output may be a reconfigured view of the input. The input image's pixel type and storage arrangement may not be preserved.

Definition at line 1022 of file vil_convert.h.

vil_image_view_base_sptr vil_convert_to_grey_using_rgb_weighting ( const vil_image_view_base_sptr & src ) [inline]

Create a greyscale image from any image src using default weights.

This function is designed to be used with vil_load or vil_image_resource::get_view() where you do not know the pixel type in advance. The output may be a reconfigured view of the input. The input image's pixel type and storage arrangement may not be preserved.

Default weights convert from linear RGB to CIE luminance assuming a modern monitor. See Charles Poynton's Colour FAQ http://www.poynton.com/ColorFAQ.html

Definition at line 1076 of file vil_convert.h.

vil_image_view_base_sptr vil_convert_to_n_planes	(	unsigned	n_planes,
		const vil_image_view_base_sptr &	src
	)		`[inline]`

Create an n plane image from any image src.

This function is designed to be used with vil_load or vil_image_resource::get_view() where you do not know the pixel type or number of planes in advance. If the input images have too many planes, the higher planes will be truncated. If the input image has too few planes, the new planes will be copies of the first plane.

The output may be a shallow copy of the input. The input image's storage arrangement may not be preserved.

This function works on scalar pixel types only, however it can be used to produce an rgb image as in the following example

 vil_image_view<vil_rgb<float> > =
   vil_convert_cast(
     vil_convert_to_component_order(
       vil_convert_to_n_planes(
         vil_load(filename),
       3),
     ),
   float());

Definition at line 1172 of file vil_convert.h.

Classes

Functions

Detailed Description

Function Documentation