Representation of an (x,y) pair of pixel coordinates. More...

#include <pixpoint.h>

Classes
struct	Is_inbounds
	Predicate functor tests whether a PixPoint is in a bounding box. More...

struct	Unused
	exception thrown if the PixPoint is used while uninitialized More...

Public Types
typedef int	Integer
	any signed integer valued type is fine More...

Public Member Functions
	PixPoint ()
	ctor sets fields to sentinel values to indicated "unused." More...

	PixPoint (Integer xx, Integer yy)
	Basic ctor builds from two coordinates. More...

void	swap (PixPoint &that)
	swap state of two pixpoints More...

bool	is_unused () const
	Test whether a PixPoint is unused (untouched since default ctor) More...

bool	is_not_unused () const
	convenience inline for better readability More...

bool	is_used () const
	another convenience inline that is not so unpositive. More...

bool	operator< (const PixPoint &pp) const
	This operator imposes a total order on PixPoints. More...

bool	operator== (const PixPoint &pp) const
	test whether two points are equivalent (same integer coords) More...

bool	operator!= (const PixPoint &pp) const
	test whether two points differ (different integer coords) More...

PixPoint &	operator+= (const PixPoint &pp)
	add a PixPoint to this PixPoint, when interpreted as 2-vectors More...

PixPoint	operator+ (const PixPoint &pp) const
	add two PixPoints when they are interpreted as 2-vectors More...

PixPoint	operator- (const PixPoint &pp) const
	subtract two PixPoints when they are interpreted as 2-vectors More...

PixPoint	operator* (int factor) const
	multiply components of a PixPoint by a factor (like 2-vector) More...

PixPoint	operator/ (int divisor) const
	integer-divide components of a PixPoint (like a 2-vector) More...

Integer	idot (const PixPoint &pp) const
	interp as 2-vec, compute dot prod as integer (beware overflow) More...

float	dist2 (const PixPoint &pp=PixPoint(0, 0)) const
	Distance squared between PixPoint objects, or from the origin. More...

float	dist (const PixPoint &pp=PixPoint(0, 0)) const
	Return distance between points, using the L2 norm. More...

Integer	L_infinity_distance (const PixPoint &pp) const

bool	adjacent8 (const PixPoint &pp) const
	test adjacency using eight-connectivity (or identity). More...

std::string	str (const std::string &sep=", ") const
	Express a PixPoint as a string (ascii coordinate values) More...

bool	in_quadrant_I () const
	Test whether a PixPoint has nonnegative x and y coordinates. More...

bool	is_poz_poz () const
	Test whether a PixPoint has strictly positive x and y coords. More...

Integer	cross (const PixPoint &pp) const
	return cross product of two PixPoints interpreted as 2-vectors. More...

bool	is_collinear (const PixPoint &p1, const PixPoint &p2) const
	return true iff this point lies on the same line as line(p1,p2). More...

Static Public Member Functions
static void	fault_if (bool b)
	throw exception if we try to operate on an unused point More...

Public Attributes
Integer	x
	x coordinate of the pixel More...

Integer	y
	y coordinate of the pixel More...

Detailed Description

Representation of an (x,y) pair of pixel coordinates.

The following structure is used to represent a single pixel coordinate in a trail image. We use a vector of them (below) to represent a trail or trail proposal within that context (i.e., without the full information provided by a struct seg.

Useful pixel methods include adjacency testing, a total order based on row- major ordering, and both L-2 and L-infinity distances between points.

This struct has a default ctor that sets the fields to a sentinel value (a large number) which indicates that the x and y coordinates have not been properly assigned valid values.

To a limited extent, you can partially use these as 2-vectors, since you can store negative coordinate values, and they have both + and - operators.

See Also: str_to_PixPoint() to construct from a string, or from a stream.

Member Typedef Documentation

typedef int kjb::qd::PixPoint::Integer

any signed integer valued type is fine

Constructor & Destructor Documentation

kjb::qd::PixPoint::PixPoint ( )

inline

ctor sets fields to sentinel values to indicated "unused."

kjb::qd::PixPoint::PixPoint	(	Integer	xx,
		Integer	yy
	)

inline

Basic ctor builds from two coordinates.

Member Function Documentation

bool kjb::qd::PixPoint::adjacent8 ( const PixPoint & pp ) const

inline

test adjacency using eight-connectivity (or identity).

Parameters

pp	point to test whether it is adjacent to this one

Returns: true iff pp is adjacent to this point: equal or 1 step away

This tests whether two pixels are adjacent under the usual 8-connected criteria. Note that a pixel is vacuously adjacent to itself, too.

Integer kjb::qd::PixPoint::cross ( const PixPoint & pp ) const

inline

return cross product of two PixPoints interpreted as 2-vectors.

Parameters

pp	other PixPoint (interpreted as 2-vector) to cross with this one.

Returns: magnitude of the resulting cross-product vector

Actually we should call this the magnitude of the cross product, since the cross product is really a vector product. However, for vectors in the X-Y plane, in a right-handed coordinate system, the direction is always the Z direction, and this returns the magnitude.

float kjb::qd::PixPoint::dist ( const PixPoint & pp = PixPoint( 0, 0 ) ) const

inline

Return distance between points, using the L2 norm.

Parameters

pp	This method returns the L2-norm distance between pp and this point (or the origin, if omitted).

Returns: Euclidean distance, unless this point or pp is unused, in which case the result is negative.

This used to use sqrtf but <cmath> lacks it, despite <math.h> promising it. However, <cmath> has overloaded versions, including one for float. In the spirit of separating interface from impl., less is in fact more.

float kjb::qd::PixPoint::dist2 ( const PixPoint & pp = PixPoint( 0, 0 ) ) const

inline

Distance squared between PixPoint objects, or from the origin.

Parameters

pp	This method returns the L2-norm distance squared between this point and pp, if pp is specified. If left unspecified, pp defaults to the origin. L2-norm distance is Euclidean distance, if you didn't know that already.

Returns: Squared distance as a float. It's float since float has a higher dynamic range than an int. If this point or pp is unused, result is negative.

Why use this method? Because it is cheaper than dist() yet produces the same partially ordered set. Formally, for all PixPoints p, q, r dist(p,r) <= dist(q,r) IFF dist2(p,r) <= dist2(q,r). Proof is trivial.

static void kjb::qd::PixPoint::fault_if ( bool b )

inlinestatic

throw exception if we try to operate on an unused point

Integer kjb::qd::PixPoint::idot ( const PixPoint & pp ) const

inline

interp as 2-vec, compute dot prod as integer (beware overflow)

bool kjb::qd::PixPoint::in_quadrant_I ( ) const

inline

Test whether a PixPoint has nonnegative x and y coordinates.

Returns: true if this point is not unused and both its coords are nonneg.

The lines x = 0 and y = 0 are partially in Quadrant I. Wait, that's not a very precise statement. The rays {(x,y) : x>=0, y=0} and {(x,y) : x=0, y>=0} are in Quadrant I. Is that worse? That's worse, isn't it? Ah well, I give up. The code is only 24 characters long; probably best just to read it.

bool kjb::qd::PixPoint::is_collinear	(	const PixPoint &	p1,
		const PixPoint &	p2
	)		const

inline

return true iff this point lies on the same line as line(p1,p2).

bool kjb::qd::PixPoint::is_not_unused ( ) const

inline

convenience inline for better readability

bool kjb::qd::PixPoint::is_poz_poz ( ) const

inline

Test whether a PixPoint has strictly positive x and y coords.

Returns: true iff this PixPoint is not unused, both coords are positive

We could rename this predicate as "in_interior_of_quadrant_I" (but let's not do that). The current name has the virtue of brevity; little else.

bool kjb::qd::PixPoint::is_unused ( ) const

inline

Test whether a PixPoint is unused (untouched since default ctor)

bool kjb::qd::PixPoint::is_used ( ) const

inline

another convenience inline that is not so unpositive.

Integer kjb::qd::PixPoint::L_infinity_distance ( const PixPoint & pp ) const

inline

This returns between this point and pp, when we use the L-infinity norm to compute distance. What's that in ordinary terms? It's the length of the longer edge of the smallest axis-aligned bounding box surrounding both points. Confusing? Maybe it's easier just to read the code below. Purpose? It's the number of pixels in the Bressenham-alg. drawn line from this point to pp, minus one.

If this point or the argument is unused, this method returns a negative value.

It would be legitimate to give pp a default value of PixPoint(0,0) just as I did for the dist2() method. I will wait to do so until it is somehow useful.

Parameters

pp	Point to which (from this point) we want to know distance

Returns: L-infinity norm distance from this point to pp.

bool kjb::qd::PixPoint::operator!= ( const PixPoint & pp ) const

inline

test whether two points differ (different integer coords)

PixPoint kjb::qd::PixPoint::operator* ( int factor ) const

inline

multiply components of a PixPoint by a factor (like 2-vector)

PixPoint kjb::qd::PixPoint::operator+ ( const PixPoint & pp ) const

inline

add two PixPoints when they are interpreted as 2-vectors

PixPoint& kjb::qd::PixPoint::operator+= ( const PixPoint & pp )

inline

add a PixPoint to this PixPoint, when interpreted as 2-vectors

PixPoint kjb::qd::PixPoint::operator- ( const PixPoint & pp ) const

inline

subtract two PixPoints when they are interpreted as 2-vectors

PixPoint kjb::qd::PixPoint::operator/ ( int divisor ) const

inline

integer-divide components of a PixPoint (like a 2-vector)

bool kjb::qd::PixPoint::operator< ( const PixPoint & pp ) const

inline

This operator imposes a total order on PixPoints.

Parameters

pp	Point to compare to this point

Returns: true iff pp is "larger" in the total order, i.e., its row major index exceeds this point's row major index (whatever width you use).

Although it does not really matter, this order reflects row-major positioning of the pixels in an array.

bool kjb::qd::PixPoint::operator== ( const PixPoint & pp ) const

inline

test whether two points are equivalent (same integer coords)

std::string kjb::qd::PixPoint::str ( const std::string & sep = ", " ) const

inline

Express a PixPoint as a string (ascii coordinate values)

void kjb::qd::PixPoint::swap ( PixPoint & that )

inline

swap state of two pixpoints

Member Data Documentation

Integer kjb::qd::PixPoint::x

x coordinate of the pixel

Integer kjb::qd::PixPoint::y

y coordinate of the pixel

The documentation for this struct was generated from the following file:

/work/kobus/src/lib/qd_cpp/pixpoint.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation