The purpose of this reference manual is to provide information about the most useful and stable classes and functions, in an easy-to-read format. Although the library is still in a state of development, the interfaces captured here are not expected to change significantly (if at all), and the functionality captured here has been tested at least to a moderate degree. While users should also feel free to use any additional functions they find in the header files themselves, keep in mind that such functions are less well tested and are more likely to have their interfaces changed in the future.
The library follows the convention of passing inputs as const references (except for native types, which are passed by value), outputs as pointers (after the inputs), and input-outputs as pointers at the beginning. Of course, due to C++ restrictions, parameters with default values (even if they are inputs) always come last. Examples:
void Foo1(const A& a, A* b); // 'a' is input, 'b' is output void Foo2(const A& a, B* b, int c=0); // same but with a default value for the last parameter void Foo3(B* b, const A& a); // 'b' is both input and outputThis syntax, similar to that used by printf() and scanf() in C, makes code more readable because you can immediately tell whether a parameter is changed by a function simply by looking at whether its pointer is passed. For example, we can tell by immediate inspection that the second line of this code does not modify img1, even without knowing anything about the semantics of the function:
ImgGray img1, img2; Func(img1, &img2); // does not modify 'img1'
The library automatically handles the allocation / reallocation, if necessary, of the internal data of outputs, so all you need to do is pass a valid pointer. For example, just pass a pointer to an image without first specifying its size. On the other hand, input-outputs are parameters whose internal values may change (perhaps as a function of their input values) but whose size remains constant.
Many of the functions check to see whether the operation is being performed in place. For example, suppose we call the function above with the same value being passed as input and output:
A a; Foo1(a, &a); // 'in-place' operationIn this case the output pointer passed to the function points to the input parameter, but the function will work correctly nevertheless. Keep in mind that some of the functions can be efficiently implemented in place, in which case the function will do so; while other functions require the allocation of a temporary variable to store the intermediate results. In the latter case, the in-place operation provides convenience for the user, but perhaps at the expense of computational overhead.
In the functions below, src is used for inputs, dst for outputs, and src_dst for input-outputs. For brevity, the notation ImgX is used when a function is implemented for multiple image types.
Image |
Overview
There are five image classes, all derived from a base templated class Image:
ImgGray : Image<unsigned char> graylevel image (one byte per pixel)
ImgBgr : Image<Bgr> blue-green-red color image (three bytes per pixel)
ImgBinary : Image<bool> packed binary image (one bit per pixel)
ImgInt : Image<int> integer image (machine dependent, but usually 4 bytes per pixel)
ImgFloat : Image<float> single-precision floating-point image (4 bytes per pixel)
The image data are stored in memory as contiguous pixels, in row major order with no padding between rows. For multi-channel images, the channels are interleaved; e.g., the pixels in ImgBgr are <B0, G0, R0, B1, G1, R1, ...>. For ImgBinary, the first pixel is stored in the most significant bit of the first byte, the ninth pixel is stored in the most significant bit of the second byte, and so forth; if the total number of pixels is not a multiple of 8, then the last byte contains unused bits.
The Bgr struct is described below in detail, but it basically contains three unsigned chars: struct Bgr { unsigned b, g, r };
Members
Typedefs:
Pixel a pixel (unsigned char, int, float, bool, Bgr, ...)
Iterator generalized pointer to a pixel
ConstIterator constant generalized pointer to a pixel
Constants:
int NBITS_PER_PIXEL number of bits per pixel
int NCHANNELS number of channels
Pixel MIN_VAL minimum pixel value
Pixel MAX_VAL maximum pixel value
Info:
int Width() const returns the width
int Height() const returns the height
int NBytes() const returns the number of bytes
Pixel data:
const Pixel& operator()(int x, int y) const access a pixel (read only)
Pixel& operator()(int x, int y) access a pixel (read / write)
ConstIterator Begin() const return iterator to first pixel (read only)
ConstIterator Begin(int x, int y) const return iterator to pixel (x,y) (read only)
ConstIterator End() const return iterator to just past last pixel (read only)
Iterator Begin() return iterator to first pixel (read / write)
Iterator Begin(int x, int y) return iterator to pixel (x,y) (read / write)
Iterator End() return iterator to just past last pixel (read / write)
const unsigned char* BytePtr() const return pointer to first byte (same as Begin() typecast to unsigned char*)
unsigned char* BytePtr() return pointer to first byte (same as Begin() typecast to unsigned char*)
Constructor / destructor / etc.
Image() create empty (0 x 0) image
Image(int width, int height) create width x height image (uninitialized values)
Image(const Image& other) make an exact replica (with a separate copy of the data)
~Image() destroy image (free up all memory)
Image& operator=(const Image& other) make an exact replica (with a separate copy of the data)
void Reset(int width, int height) resizes image to width x height (does not initialize values),
-- does nothing if width x height image already allocated
void Reset() free memory for image data
-- does nothing if image is already empty
Matrix |
There are two matrix classes, all derived from a base templated class Matrix:
MatFlt : Matrix<float> single-precision floating point matrix (32 bits per element)
MatDbl : Matrix<double> double-precision floating point matrix (64 bits per element)
The interface to the matrix class is very similar to the image class.
Bgr |
struct Bgr { unsigned b, g, r };
Point / Rect |
typedef CPoint Point
typedef CRect Rect
In the future, they may be reimplemented, but their interfaces should remain consistent
with those of the MFC classes.
Exception |
Display() display the human-readable string in a message box.Note: If you would like to throw an Exception yourself, pass a human-readable string to the macro BLEPO_ERROR(). To format the string in the same line, using StringEx:
BLEPO_ERROR("Out of bounds");
BLEPO_ERROR(StringEx("Unable to open file %s", filename));
Load |
void Load(const char* filename, ImgBgr* out); void Load(const char* filename, ImgGray* out);Loads an image from a file into out, allocating memory for out. Supported file formats: BMP, PGM (binary), PPM (binary), JPEG. The file type is determined automatically by the magic number in the file (ignoring the file extension).
Save |
void Save(const ImgBgr& img, const char* filename, const char* filetype = NULL); void Save(const ImgGray& img, const char* filename, const char* filetype = NULL);Saves an image to a file. Supported file formats: BMP, PGM (binary), PPM (binary), JPEG. The image type is determined automatically by the extension of filename (".bmp", ".pgm", ".ppm", ".jpg", or ".jpeg"). If the filename has a nonstandard extension, pass the standard extension as an optional third parameter (without the period). For example,
Save(img, "file.jaypegg", "jpg");
Convert |
void Convert(const ImgX& img, ImgY* out);Converts between two image types, allocating memory for out. ImgX and ImgY may be any pair of distinct image types, with the following meaning:
ImgGray -> ImgBgr replicates graylevel value three times ImgGray -> ImgInt copies values ImgGray -> ImgFloat copies values ImgGray -> ImgBinary sets nonzero pixels to 1, zero pixels to 0 ImgInt -> ImgGray clips values outside [0, 255] ImgInt -> ImgFloat copies values ImgInt -> ImgBgr varies (see below) ImgInt -> ImgBinary same as ImgInt -> ImgGray -> ImgBinary ImgFloat -> ImgGray rounds values, then clips to [0, 255] ImgFloat -> ImgInt rounds values ImgFloat -> ImgBgr same as ImgFloat -> ImgGray -> ImgBgr ImgFloat -> ImgBinary same as ImgFloat -> ImgGray -> ImgBinary ImgBgr -> ImgGray uses (1*B + 6*G + 3*R)/10 ImgBgr -> ImgInt varies (see below) ImgBgr -> ImgFloat same as ImgBgr -> ImgGray -> ImgFloat ImgBgr -> ImgBinary same as ImgBgr -> ImgGray -> ImgBinary ImgBinary -> ImgGray sets 0 to zero, 1 to 255 ImgBinary -> ImgInt sets 0 to zero, 1 to one ImgBinary -> ImgFloat sets 0 to zero, 1 to one ImgBinary -> ImgBgr sets 0 to zero, 1 to Bgr(255,255,255)
The functions converting between ImgBgr and ImgInt require a third parameter to indicate the format of the integer:
In addition, the functions converting from ImgBinary require two additional parameters: the zerovalue and the onevalue. For example, to set all the 0 pixels to blue and all the 1 pixels to red, use the following:
Convert(img_binary, &img_bgr, Bgr(255,0,0), Bgr(0,0,255));
Threshold |
void Threshold(const ImgX& img, ImgX::Pixel threshold, ImgBinary* out);
Thresholds an image, setting the dimensions of out to those of img. Pixels greater than or equal to threshold are set to 1, otherwise to 0.
Defined for ImgGray, ImgInt, ImgFloat.
Set |
void Set(ImgX* out, ImgX::Pixel val); void Set(ImgX* out, const Rect& rect, ImgX::Pixel val); void Set(ImgX* out, const ImgBinary& mask, ImgX::Pixel val); void Set(ImgX* out, const Point& pt, const ImgX& img); void Set(ImgX* out, const Point& pt, const ImgX& img, const Rect& rect); void SetOutside(ImgX* out, const Rect& rect, ImgX::Pixel val);
Sets the pixels in out to the value val. Does not change the dimensions of out. These six versions, respectively,
Defined for all image types.
Extract |
void Extract(const ImgX& img, const Rect& rect, ImgX* out);
Copies the values in rect of img to out, resizing the latter to the size of the rectangle.
Defined for all image types.
IsSameSize |
bool IsSameSize(const ImgX& img1, const ImgY& img2);
Returns whether two images have the same dimensions.
Defined for all image types. Images may be of the same or different types.
IsIdentical |
bool IsIdentical(const ImgX& img1, const ImgX& img2);
Returns whether two images have the same dimensions and the exact same data.
Defined for all image types.
Comparison |
void Equal(const ImgX& img1, const ImgX& img2, ImgBinary* out); void NotEqual(const ImgX& img1, const ImgX& img2, ImgBinary* out); void LessThan(const ImgFloat& img1, const ImgFloat& img2, ImgBinary* out); void GreaterThan(const ImgX& img1, const ImgX& img2, ImgBinary* out); void LessThanOrEqual(const ImgX& img1, const ImgX& img2, ImgBinary* out); void GreaterThanOrEqual(const ImgX& img1, const ImgX& img2, ImgBinary* out);
Sets a binary image based upon a pixel-wise comparison of two images, resizing out to the same size as the input images (which must be of the same size).
Equal, NotEqual are defined for all image types. The other functions are defined only for ImgGray, ImgInt, ImgFloat.
Min / Max |
ImgX::Pixel Min(const ImgX& img); ImgX::Pixel Max(const ImgX& img); void MinMax(const ImgX& img, ImgX::Pixel* minn, ImgX::Pixel* maxx); void Min(const ImgX& img1, const ImgX& img2, ImgX* out); void Max(const ImgX& img1, const ImgX& img2, ImgX* out);
The first two functions return the min or max value of an image. The next function computes the min and max simultaneously and is more efficient if both are needed (because only one pass through the image data is performed). The last two functions set out to the pixel-wise min or max of the two images, resizing out to the same size as the input images (which must be of the same size).
Defined for ImgGray, ImgInt, ImgFloat.
Logical operations |
Two input images: void And(const ImgX& img1, const ImgX& img2, ImgX* out); void Or (const ImgX& img1, const ImgX& img2, ImgX* out); void Xor(const ImgX& img1, const ImgX& img2, ImgX* out); One input image and a binary mask: void And(const ImgX& img1, const ImgBinary& mask, ImgX* out); void Or (const ImgX& img1, const ImgBinary& mask, ImgX* out); void Xor(const ImgX& img1, const ImgBinary& mask, ImgX* out); One input image and a constant value: void Not(const ImgX& img, ImgX* out); void And(const ImgX& img, ImgX::Pixel val, ImgX* out); void Or (const ImgX& img, ImgX::Pixel val, ImgX* out); void Xor(const ImgX& img, ImgX::Pixel val, ImgX* out);
Sets out by applying a bitwise logical operator to an image or pair of images. The two input images must be of the same size.
Notes:
Arithmetic operations |
void Add (const ImgX& img1, const ImgX& img2, ImgX* out); void Subtract(const ImgX& img1, const ImgX& img2, ImgX* out); void AbsDiff (const ImgX& img1, const ImgX& img2, ImgX* out); void Multiply(const ImgX& img1, const ImgX& img2, ImgX* out); void Multiply(const ImgX& img1, const ImgX::Pixel& img2, ImgX* out); void Divide (const ImgX& img1, const ImgX::Pixel& img2, ImgX* out); void LinearlyScale(const ImgX& img, ImgX::Pixel minval, ImgX::Pixel maxval, ImgX* out);
Applies a pixel-wise arithmetic operator to an image or pair of images. The two input images must be of the same size. LinearlyScale scales the image so that its minimum value is 'minval' and maximum value is 'maxval'.
Notes:
Resampling |
void Resample(const ImgX& img, int new_width, int new_height, ImgX* out); void Upsample(const ImgX& img, int factor_x, int factor_y, ImgX* out); void Downsample(const ImgX& img, int factor_x, int factor_y, ImgX* out);
Creates an image with new dimensions from an existing image. Resample is the most general function because it can create an image with arbitrary dimensions. Upsample and Downsample can create an image whose dimensions are an integral multiple of the original image. The factors must be positive.
Defined for all image types.
Note: Only nearest-neighbor interpolation is supported for these functions.
Interpolation |
ImgX::Pixel Interp(const ImgX& img, float x, float y);
Performs bilinear interpolation at a single pixel. Defined for all image types.
Display image |
void Draw(const ImgX& img, HDC hdc, int x, int y); void Draw(const ImgX& img, HDC hdc, const Rect& src, const Rect& dst);
Draws an image onto a Windows device context (Note: A CDC may be substituted for an HDC). The first function draws the image at a specified location with no stretching of the image. The second function draws an arbitrary rectangle of the image onto an arbitrary rectangle of the device context, automatically stretching the image to fit the destination rectangle.
Defined for all image types. Binary, float, and int images are linearly scaled to map their inputs to the range [0,255].
Draw onto image |
void DrawDot(const Point& pt, ImgX* out, const X& color, int size = 3); // draws a filled-in square void DrawLine(const Point& pt1, const Point& pt2, ImgX* out, const X& color, int thickness=1); void DrawRect(const Rect& rect, ImgX* out, const X& color, int thickness=1); void DrawCircle(const Point& center, int radius, ImgX* out, const X& color, int thickness=1); void DrawEllipse(const Point& center, int major_axis, int minor_axis, double angle, ImgX* out, const X& color, int thickness=1); void DrawEllipticArc(const Point& center, int major_axis, int minor_axis, double angle, double start_angle, double end_angle, ImgX* out, const X& color, int thickness=1);
Draws a dot, line, rectangle, circle, ellipse, or elliptic arc, respectively, on an image. Implementation uses OpenCV functions.
class TextDrawer:
TextDrawer(int height=15, int thickness=2);
void DrawText(ImgBgr* img, const char* text, const Point& pt, const Bgr& color);
void DrawText(ImgBgr* img, const char* text, const Point& pt, const Bgr& color, const Bgr& background_color);
Draws text onto an image.
Morphological operations |
binary morphology: void Erode3x3 (const ImgGray& img, ImgGray* out); void Dilate3x3 (const ImgGray& img, ImgGray* out); void Erode3x3Cross (const ImgGray& img, ImgGray* out); void Dilate3x3Cross(const ImgGray& img, ImgGray* out); grayscale morphology: void GrayscaleErode3x3 (const ImgGray& img, int offset, ImgGray* out); void GrayscaleDilate3x3(const ImgGray& img, int offset, ImgGray* out);
Performs dilation or erosion with one of the following 3 x 3 kernels:
1 1 1 0 1 0
1 1 1 1 1 1
1 1 1 0 1 0
(cross)
The binary functions treat the input image as a binary image and are optimized for MMX. The grayscale functions use a 3x3 structuring element of all ones, multiplied by 'offset' (which should be non-negative).
Convolution / Gradient / Smoothing / etc. |
void SmoothGauss5x5(const ImgGray& img, ImgGray* out); void GradMagPrewitt(const ImgGray& img, ImgGray* out); void GradPrewittX(const ImgGray& img, ImgFloat* out); void GradPrewittY(const ImgGray& img, ImgFloat* out); void GradPrewitt (const ImgGray& img, ImgFloat* gradx, ImgFloat* grady); void Smooth (const ImgFloat& img, float sigma, int kernel_length, ImgFloat* img_smoothed); void Smooth (const ImgFloat& img, float sigma, ImgFloat* img_smoothed); void Gradient(const ImgFloat& img, float sigma, int kernel_length, ImgFloat* gradx, ImgFloat* grady); void Gradient(const ImgFloat& img, float sigma, ImgFloat* gradx, ImgFloat* grady);
**** Mention borders. Mention efficiency. Add functions to use MMX routines we already have implemented. Gradient uses the derivative of a Gaussian.
Connected components |
void ConnectedComponents4(const ImgBgr & img, ImgInt* labels); void ConnectedComponents4(const ImgBinary& img, ImgInt* labels); void ConnectedComponents4(const ImgGray & img, ImgInt* labels); void ConnectedComponents4(const ImgInt & img, ImgInt* labels);
Computes the connected components of an image using 4 neighbors. An optional third argument, of type
std::vector