Wrapped version of the C struct KJB_image. More...

#include <i_image.h>

Inheritance diagram for kjb::Image:

Public Types
enum	RGB_channel { RED, GREEN, BLUE, END_CHANNELS }
	Constants for accessing color channels via number, with at(). More...

typedef kjb_c::KJB_image	Impl_type

typedef kjb_c::Pixel	Pixel_type

Public Member Functions
	Image (int rows=0, int cols=0)
	Construct image of specified size, defaults to zero by zero. More...

	Image (const kjb_c::Matrix &src)
	Construct grayscale image from c-style matrix. More...

	Image (const Matrix &src)
	Construct grayscale image from matrix. More...

	Image (const Image &src)
	Copy ctor, performs a deep copy (use sparingly) More...

	Image (const std::string &fname)
	Read image from a named file. More...

	Image (Impl_type *wrap_me)
	Wrap up an "unsafe" image so it is certain to be destroyed. More...

	Image (int num_rows, int num_cols, int r, int g, int b)
	Create an image with pixels initialized to the given value. More...

virtual	~Image ()
	Dtor simply wraps kjb_free_image() More...

void	swap (Image &other)
	Swap the implementation of two images. More...

Image &	scale (double factor)
	Scale the image by factor using imagemagick (deprecated). More...

Image &	crop (int r, int c, int num_rows, int num_cols)
	Crop this image. More...

void	write (const std::string &fname) const
	Write to a file. More...

int	get_num_rows () const
	Return the number of rows in the image. More...

int	get_num_cols () const
	Return the number of columns in the image. More...

int	get_length () const
	Return the number of elements (pixels) in the image. More...

Image &	operator= (const kjb_c::KJB_image &src)
	Deep copy assignment from C-type image. More...

Image &	operator= (const Image &src)
	Deep copy assignment. More...

Image &	operator+= (const Image &op2)
	Add an image from this image, in place. More...

Image &	operator-= (const Image &op2)
	Subtract an image from this image, in place. More...

Image &	operator*= (double op2)
	Multiply this image by a scalar; i.e., scale this image in channel space. More...

Image &	operator/= (double op2)
	Divide this image by a scalar; i.e., scale this image in channel space. More...

float &	operator() (int row, int col, int channel)
	Unchecked access of lvalue at given row, column, and RGB_channel. More...

float	operator() (int row, int col, int channel) const
	Unchecked access of rvalue at given row, column, and RGB_channel. More...

Pixel_type &	operator() (int row, int col)
	Lvalue pixel access at given row & column, no bounds-checking. The coordinates are row,column NOT x,y ! More...

const Pixel_type &	operator() (int row, int col) const
	Rvalue pixel access at given row & column, no bounds-checking. The coordinates are row,column NOT x,y ! More...

Pixel_type &	operator() (int index)
	Access lvalue at row-major index, without bounds-checking. More...

const Pixel_type &	operator() (int index) const
	Access rvalue at row-major index, without bounds-checking. More...

void	invert ()
	Invert this image; i.e., dark becomes light and vice-versa. More...

Image	get_inverted () const
	Generate an inverted version of this image (deprecated). More...

Matrix	get_channel (int index) const

void	check_bounds (int row, int col) const
	Test whether row, column coordinates are valid. More...

float &	at (int row, int col, int channel)
	Access lvalue of pixel channel at row, column coordinates. More...

float	at (int row, int col, int channel) const
	Access rvalue of pixel channel at row, column coordinates. More...

Pixel_type &	at (int row, int col)
	Access pixel lvalue at row, column coordinates. More...

const Pixel_type &	at (int row, int col) const
	Access pixel rvalue at row, column coordinates. More...

const Pixel_type &	at (int index) const
	Access pixel rvalue at row-major index. More...

Pixel_type &	at (int index)
	Access pixel lvalue at row-major index. More...

const Impl_type *	c_ptr () const
	Access a pointer to the underlying implementation. More...

Impl_type *	non_const_c_ptr () const
	Access a pointer to the underlying implementation, use with care. More...

void	set_c_ptr (Impl_type *iimage)
	set this matrix to point to a different c memory, freeing the previously pointed area More...

Matrix	to_grayscale_matrix () const
	Convert this image to a single matrix by simple averaging of the pixels. More...

Matrix	to_grayscale_matrix (double r_w, double g_w, double b_w) const
	Convert this image to a single matrix by weighted averaging of the pixels. More...

Matrix	to_channel_matrix (RGB_channel channel) const
	Convert this image to a single matrix by simple averaging of the pixels. More...

Int_matrix	to_color_matrix (double scale=1.0) const
	Convert this image to a single matrix containing RGBA values. The first eight least significant bits are red, the next least least significant octet is green, and so on. More...

void	from_color_matrix (const Int_matrix &m)
	Construct an image from a matrix containing RGBA values. Each element of matrix m is an integer which consists of ... More...

void	from_color_matrices (const Matrix &red, const Matrix &green, const Matrix &blue)
	Contruct an image from three matrices representing red, green, blue channels. More...

template<class InputIterator >
Vector	intensity_histogram (InputIterator first, InputIterator last) const
	Computes the intensity histogram of a region – given by a range of pairs – of this image. More...

void	draw_point (int row, int col, int width, Pixel_type p)
	Draw a point on the image. More...

void	draw_line_segment (int row_from, int col_from, int row_to, int col_to, int width, Pixel_type p)
	Draw a line segment on the image. More...

void	draw_arrow (const Vector &src, const Vector &dest, const Image::Pixel_type pixel)
	Draw an arrow from src to dest. More...

template<class Iterator >
void	draw_polyline (Iterator begin, Iterator end, int width, Pixel_type p)
	Draw a polyline on the image, i.e., a chain of line segments. More...

void	draw_aa_rectangle (int first_row, int first_col, int last_row, int last_col, Pixel_type p)
	Draw a solid, axis-aligned rectangle on the image. More...

void	draw_aa_rectangle_outline (int first_row, int first_col, int last_row, int last_col, Pixel_type p)
	Draw the outline of an, axis-aligned rectangle on the image. More...

void	draw_circle (int center_row, int center_col, int radius, int line_width, Pixel_type p)
	Draw a circle on the image. More...

void	draw_disk (int center_row, int center_col, int radius, Pixel_type p)
	draw a disk (a filled circle) on the image, of a given color. More...

int	draw_text_center (int row, int col, const std::string &text, const std::string &font_file="times14")
	Draw the text on the image. More...

int	draw_text_top_left (int row, int col, const std::string &text, const std::string &font_file="times14")
	Draw the text on the image. More...

void	draw_image (const kjb_c::KJB_image *overlay, int row=0, int col=0, int scale=1)
	Overlay another image on this image, with an optional offset. More...

void	draw_image (const Image &overlay, int row=0, int col=0, int scale=1)
	This is an overload of draw_image() taking a C-style pointer. More...

int	display (const std::string &title=std::string()) const
	Show the image and return an image number (for closing later). More...

int	get_flags () const
	return copy of the "flags" field of underlying KJB_image object More...

int	set_flags (int new_flags)
	set "flags" field of underlying KJB_image; return previous flags More...

Static Public Member Functions
static Image	create_zero_image (int rows, int cols)
	Create an empty image of valid zero pixels, r=g=b=0. More...

static Image	create_initialized_image (int rows, int cols, int r, int g, int b)
	Create an empty image with pixels initialized to (r, g, b) More...

Protected Attributes
Impl_type *	m_image

Friends
void	swap (kjb::Image &a, kjb::Image &b)

Detailed Description

Wrapped version of the C struct KJB_image.

Due to memory leaks associated with the kjb_display_image function – leaks that are still unresolved – this class has some debug features I've wrapped up under the heading "Garbage Police." Look for the above macro. If the Garbage Police are turned off, then this is a very thin wrapper on the KJB_image class. Otherwise there is some static tracking of the number of instances of this class. This class does not seem to leak; the leaks must be elsewhere (i.e., not my fault).

Member Typedef Documentation

typedef kjb_c::KJB_image kjb::Image::Impl_type

typedef kjb_c::Pixel kjb::Image::Pixel_type

Member Enumeration Documentation

enum kjb::Image::RGB_channel

Constants for accessing color channels via number, with at().

Enumerator
RED
GREEN
BLUE
END_CHANNELS

Constructor & Destructor Documentation

kjb::Image::Image	(	int	rows = `0`,
		int	cols = `0`
	)

Construct image of specified size, defaults to zero by zero.

kjb::Image::Image ( const kjb_c::Matrix & src )

explicit

Construct grayscale image from c-style matrix.

kjb::Image::Image ( const Matrix & src )

explicit

Construct grayscale image from matrix.

kjb::Image::Image ( const Image & src )

Copy ctor, performs a deep copy (use sparingly)

kjb::Image::Image ( const std::string & fname )

explicit

Read image from a named file.

This wraps C-library function kjb_read_image_2().

Exceptions

KJB_error if the underlying C function returns an error.

kjb::Image::Image ( Impl_type * wrap_me )

explicit

Wrap up an "unsafe" image so it is certain to be destroyed.

kjb::Image::Image	(	int	num_rows,
		int	num_cols,
		int	r,
		int	g,
		int	b
	)

Create an image with pixels initialized to the given value.

virtual kjb::Image::~Image ( )

inlinevirtual

Dtor simply wraps kjb_free_image()

Member Function Documentation

float & kjb::Image::at	(	int	row,
		int	col,
		int	channel
	)

Access lvalue of pixel channel at row, column coordinates.

Exceptions

Index_out_of_bounds if the coordinates are out of bounds.

float kjb::Image::at	(	int	row,
		int	col,
		int	channel
	)		const

Access rvalue of pixel channel at row, column coordinates.

Exceptions

Index_out_of_bounds if the coordinates are out of bounds. The coordinates are row,column NOT x,y !

Image::Pixel_type & kjb::Image::at	(	int	row,
		int	col
	)

Access pixel lvalue at row, column coordinates.

Exceptions

Index_out_of_bounds if the coordinates are out of bounds. The coordinates are row,column NOT x,y !

const Image::Pixel_type & kjb::Image::at	(	int	row,
		int	col
	)		const

Access pixel rvalue at row, column coordinates.

Exceptions

Index_out_of_bounds if the coordinates are out of bounds. The coordinates are row,column NOT x,y !

const Image::Pixel_type & kjb::Image::at ( int index ) const

Access pixel rvalue at row-major index.

Exceptions

Index_out_of_bounds if the coordinates are out of bounds.

Image::Pixel_type & kjb::Image::at ( int index )

Access pixel lvalue at row-major index.

Exceptions

Index_out_of_bounds if the coordinates are out of bounds.

const Image::Impl_type * kjb::Image::c_ptr ( ) const

Access a pointer to the underlying implementation.

void kjb::Image::check_bounds	(	int	row,
		int	col
	)		const

Test whether row, column coordinates are valid.

Exceptions

Index_out_of_bounds if the coordinates are out of bounds.

Image kjb::Image::create_initialized_image	(	int	rows,
		int	cols,
		int	r,
		int	g,
		int	b
	)

static

Create an empty image with pixels initialized to (r, g, b)

static Image kjb::Image::create_zero_image	(	int	rows,
		int	cols
	)

inlinestatic

Create an empty image of valid zero pixels, r=g=b=0.

Image & kjb::Image::crop	(	int	r,
		int	c,
		int	num_rows,
		int	num_cols
	)

Crop this image.

int kjb::Image::display ( const std::string & title = std::string() ) const

Show the image and return an image number (for closing later).

See Also: close_displayed_image()

This will try to show the image on the screen, in a window. The window title optionally may be (partially) specified with the 'title' parameter. Double quotes in the title will be altered, sorry. The display will persist even after the Image object is destroyed; this is a feature, not a bug. You can kill it with close_displayed_image().

Bug:: Whenever this function is called, a memory leak is reported.

void kjb::Image::draw_aa_rectangle	(	int	first_row,
		int	first_col,
		int	last_row,
		int	last_col,
		Pixel_type	p
	)

Draw a solid, axis-aligned rectangle on the image.

This would be more elegant if the first row were filled and the last row was just BEYOND the fill, but we don't do it that way. The first row, last row, first column, and last column are all affected. If the first and last indices are not increasing they are silently swapped.

This performs clipping silently. If any of the row or column indices are out of bounds, nothing bad happens; the box is simply clipped.

The "aa" is for "axis-aligned."

Parameters

first_row	Index of the first filled row of the rectangle
first_col	Index of the first filled col. of rectangle
last_row	Index of the last filled row of the rectangle
last_col	Index of the last filled col. of the rectangle
p	Pixel (color) with which to fill

void kjb::Image::draw_aa_rectangle_outline	(	int	first_row,
		int	first_col,
		int	last_row,
		int	last_col,
		Pixel_type	p
	)

Draw the outline of an, axis-aligned rectangle on the image.

This would be more elegant if the first row were filled and the last row was just BEYOND the fill, but we don't do it that way. The first row, last row, first column, and last column are all affected. If the first and last indices are not increasing they are silently swapped.

This performs clipping silently. If any of the row or column indices are out of bounds, nothing bad happens; the box is simply clipped.

The "aa" is for "axis-aligned."

Parameters

first_row	Index of the first filled row of the rectangle
first_col	Index of the first filled col. of rectangle
last_row	Index of the last filled row of the rectangle
last_col	Index of the last filled col. of the rectangle
p	Pixel (color) with which to fill

void kjb::Image::draw_arrow	(	const Vector &	src,
		const Vector &	dest,
		const Image::Pixel_type	pixel
	)

Draw an arrow from src to dest.

Parameters

src	source location as an (x,y) value, within image boundaries
dest	destination location as an (x,y) value, within image bounds
pixel	color of the arrow

Warning: src and dest have (x,y) semantics, where x is column, y is row.

void kjb::Image::draw_circle	(	int	center_row,
		int	center_col,
		int	radius,
		int	line_width,
		Pixel_type	p
	)

Draw a circle on the image.

Draws a circle (an empty circle .... not a disk!) of the specified radius and line width on the image, with center at (center_row, center_col).

See Also: draw_disk

Parameters

center_row	Index of the center row of the circle
center_col	Index of the center column of the circle
radius	Index of the radius of the circle
line_width	approx. thickness of the circle (0 = hairline)
p	Pixel (color) with which to draw

void kjb::Image::draw_disk	(	int	center_row,
		int	center_col,
		int	radius,
		Pixel_type	p
	)

draw a disk (a filled circle) on the image, of a given color.

See Also: draw_circle

Clipping occurs silently: disk need not lie fully within the image.

Parameters

center_row	Index of the center row of the circle
center_col	Index of the center column of the circle
radius	Index of the radius of the circle
p	Pixel (color) with which to draw

void kjb::Image::draw_image	(	const kjb_c::KJB_image *	overlay,
		int	row = `0`,
		int	col = `0`,
		int	scale = `1`
	)

Overlay another image on this image, with an optional offset.

This just forwards a call to kjb_c::image_draw_image().

Parameters

overlay	Points to an image that will be drawn onto this image
row	Index of the row of this image where the top of the overlay will be drawn
col	Index of the column of this image where the left edge of the overlay will be drawn
scale	Optional shrink factor of the overlay image; if equal to 1, the overlay is drawn full-size. If equal to 2, the overlay is drawn at half-size, etc. This number must be positive.

Clipping occurs silently: the whole overlay need not fit; nor does row or col need to be within the bounds of this image. For example, you could crop the top edge of overlay by using a negative value for row.

void kjb::Image::draw_image	(	const Image &	overlay,
		int	row = `0`,
		int	col = `0`,
		int	scale = `1`
	)

This is an overload of draw_image() taking a C-style pointer.

void kjb::Image::draw_line_segment	(	int	row_from,
		int	col_from,
		int	row_to,
		int	col_to,
		int	width,
		Pixel_type	p
	)

Draw a line segment on the image.

Parameters

row_from	Index of starting row
col_from	Index of starting column
row_to	Index of ending row
col_to	Index of ending column
width	Width of segment
p	Pixel (color) with which to fill

void kjb::Image::draw_point	(	int	row,
		int	col,
		int	width,
		Image::Pixel_type	p
	)

Draw a point on the image.

Draw a point on the image in the given location, with the given width and pixel color.

Parameters

row	Index of the first filled row of the rectangle
col	Index of the first filled col. of rectangle
width	Width of point
p	Pixel (color) with which to fill

template<class Iterator >

void kjb::Image::draw_polyline	(	Iterator	begin,
		Iterator	end,
		int	width,
		Pixel_type	p
	)

inline

Draw a polyline on the image, i.e., a chain of line segments.

Sequence is provided as an iterator range, which points to vectors representing (u,v) coordinates (i.e., (col, row) coordinates). Suitable vector types are any that implement the kjb::SimpleVector concept. This includes kjb::Vector and std::vector<double>.

Parameters

p	Pixel (color) with which to fill

int kjb::Image::draw_text_center	(	int	row,
		int	col,
		const std::string &	text,
		const std::string &	font_file = `"times14"`
	)

Draw the text on the image.

See Also: kjb_c::image_draw_text_center

Returns: kjb_c::ERROR or kjb_c::NO_ERROR to indicate success or failure.

Draws the text on the image with the center at location (row, col).

int kjb::Image::draw_text_top_left	(	int	row,
		int	col,
		const std::string &	text,
		const std::string &	font_file = `"times14"`
	)

Draw the text on the image.

See Also: kjb_c::image_draw_text_top_left

Returns: kjb_c::ERROR or kjb_c::NO_ERROR to indicate success or failure.

Draws the text on the image with the top-left at location (row, col)

void kjb::Image::from_color_matrices	(	const Matrix &	red,
		const Matrix &	green,
		const Matrix &	blue
	)

Contruct an image from three matrices representing red, green, blue channels.

Exceptions

KJB_error (possibly) if matrices not the same size (see below).

Deprecated:: Use rgb_matrices_to_image in new code.

void kjb::Image::from_color_matrix ( const Int_matrix & m )

Construct an image from a matrix containing RGBA values. Each element of matrix m is an integer which consists of ...

Todo:: finish the documentation here

Matrix kjb::Image::get_channel ( int index ) const

Note: DEPRECATED!! Use to_grayscale_matrix(double, double, double)

int kjb::Image::get_flags ( ) const

inline

return copy of the "flags" field of underlying KJB_image object

Image kjb::Image::get_inverted ( ) const

inline

Generate an inverted version of this image (deprecated).

Deprecated:: use non-member function get_inverted(const Image&) instead.

int kjb::Image::get_length ( ) const

inline

Return the number of elements (pixels) in the image.

int kjb::Image::get_num_cols ( ) const

inline

Return the number of columns in the image.

int kjb::Image::get_num_rows ( ) const

inline

Return the number of rows in the image.

void kjb::Image::invert ( )

Invert this image; i.e., dark becomes light and vice-versa.

Note: This simply wraps a call to kjb_c::ow_invert_image().

Impl_type* kjb::Image::non_const_c_ptr ( ) const

inline

Access a pointer to the underlying implementation, use with care.

DEPRECATED

Deprecated:

float& kjb::Image::operator()	(	int	row,
		int	col,
		int	channel
	)

inline

Unchecked access of lvalue at given row, column, and RGB_channel.

See Also: at() method, which provides bounds checking. The coordinates are row,column NOT x,y !

float kjb::Image::operator()	(	int	row,
		int	col,
		int	channel
	)		const

inline

Unchecked access of rvalue at given row, column, and RGB_channel.

See Also: at() method, which provides bounds checking. The coordinates are row,column NOT x,y !

Pixel_type& kjb::Image::operator()	(	int	row,
		int	col
	)

inline

Lvalue pixel access at given row & column, no bounds-checking. The coordinates are row,column NOT x,y !

const Pixel_type& kjb::Image::operator()	(	int	row,
		int	col
	)		const

inline

Rvalue pixel access at given row & column, no bounds-checking. The coordinates are row,column NOT x,y !

Pixel_type& kjb::Image::operator() ( int index )

inline

Access lvalue at row-major index, without bounds-checking.

const Image::Pixel_type & kjb::Image::operator() ( int index ) const

Access rvalue at row-major index, without bounds-checking.

Image & kjb::Image::operator*= ( double op2 )

Multiply this image by a scalar; i.e., scale this image in channel space.

Returns: an lvalue to this matrix

Image & kjb::Image::operator+= ( const Image & op2 )

Add an image from this image, in place.

Add an image to this image, in place.

Image & kjb::Image::operator-= ( const Image & op2 )

Subtract an image from this image, in place.

Image & kjb::Image::operator/= ( double op2 )

Divide this image by a scalar; i.e., scale this image in channel space.

Returns: an lvalue to this matrix

Exceptions

Divide_by_zero if the scalar value is zero

Image & kjb::Image::operator= ( const kjb_c::KJB_image & src )

Deep copy assignment from C-type image.

Image & kjb::Image::operator= ( const Image & src )

Deep copy assignment.

Image& kjb::Image::scale ( double factor )

inline

Scale the image by factor using imagemagick (deprecated).

Deprecated:: use non-member function scale_image().

void kjb::Image::set_c_ptr ( Impl_type * iimage )

inline

set this matrix to point to a different c memory, freeing the previously pointed area

DEPRECATED

Parameters

iimage the new c matrix to be wrapped by this c++ class

Deprecated:

int kjb::Image::set_flags ( int new_flags )

inline

set "flags" field of underlying KJB_image; return previous flags

void kjb::Image::swap ( Image & other )

inline

Swap the implementation of two images.

Matrix kjb::Image::to_channel_matrix ( RGB_channel channel ) const

Convert this image to a single matrix by simple averaging of the pixels.

Note: Not sure if this should exist. Perhaps to_grayscale_matrix is enough? Might disappear.

Int_matrix kjb::Image::to_color_matrix ( double scale = 1.0 ) const

Convert this image to a single matrix containing RGBA values. The first eight least significant bits are red, the next least least significant octet is green, and so on.

Matrix kjb::Image::to_grayscale_matrix ( ) const

Convert this image to a single matrix by simple averaging of the pixels.

Matrix kjb::Image::to_grayscale_matrix	(	double	r_w,
		double	g_w,
		double	b_w
	)		const

Convert this image to a single matrix by weighted averaging of the pixels.

Warning: this routine is sensitive to the value of the Pixel.extra.invalid field, and will return a matrix full of -99s (DBL_MISSING) if that field does not contain value VALID_PIXEL. However, this field is a union with alpha values, so you can't use alpha in such images.

Parameters

r_w	Weight of red channel.
g_w	Weight of green channel.
b_w	Weight of blue channel.

void kjb::Image::write ( const std::string & fname ) const

Write to a file.

Parameters

fname Filename to write to. Include a format suffix, please!

Exceptions

KJB_error,if anything goes wrong in kjb_write_image().

This wraps C function kjb_c::kjb_write_image(), and infers the proper output format from the filename suffix; or it uses a Sun format if no suffix is recognized.

Friends And Related Function Documentation

void swap	(	kjb::Image &	a,
		kjb::Image &	b
	)

friend

Member Data Documentation

Impl_type* kjb::Image::m_image

protected

The documentation for this class was generated from the following files:

/work/kobus/src/lib/i_cpp/i_image.h
/work/kobus/src/lib/i_cpp/i_image.cpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation