DLImage Class Reference

The DLImage object is the entry point for performing image processing capabilities supported by DOCLIB. More...

#include <DLImage.h>

Inheritance diagram for DLImage:

DLTextImage List of all members.

Public Types

enum  DLFlipDirection { DL_HORIZONTAL = 1, DL_VERTICAL = 2 }
enum  DLColorChannels { DL_INVALID_CHANNEL = -1, DL_RED_CHANNEL = 0, DL_GREEN_CHANNEL = 1, DL_BLUE_CHANNEL = 2 }

Public Member Functions

 DLImage ()
 DLImage (const DLImage &orig)
 DLImage (DL_BYTE *data, const DLImageHead &imageHead)
 DLImage (int w, int h, DLImageHead::DLBitDepths depth)
 DLImage (int w, int h, int depth)
 DLImage (const char *filename, DLBaseImage *imageType=NULL)
 DLImage (const void *pMemLoc, int nSize, DLBaseImage *imageType=NULL)
virtual ~DLImage ()
DLImageoperator= (const DLImage &image)
void dlLoadImage (const char *filename, DLBaseImage *imageType=NULL)
void dlLoadImage (const void *pMemLoc, const int nSize, DLBaseImage *imageType=NULL)
void dlSaveImage (const char *filename, DLBaseImage *imageType=NULL) const
void * dlSaveImageToMem (int &nSize, DLBaseImage *imageType) const
DLImageHead dlGetImageHead () const
int dlGetWidth () const
int dlGetHeight () const
int dlGetChannels () const
DLImageHead::DLBitDepths dlGetDepth () const
DLColor::DLColorTypes dlGetColorModel () const
int dlGetDataOrder () const
int dlGetRowSize () const
DLImageHead::DLDataAlignments dlGetDataAlignment () const
float dlGetHorizontalResolution () const
float dlGetVerticalResolution () const
bool dlGetResolutionFlag () const
void dlSetHorizontalResolution (int resolution)
void dlSetVerticalResolution (int resolution)
void dlSetHorizontalResolution (float resolution)
void dlSetVerticalResolution (float resolution)
void dlSetResolutionFlag (bool resflag)
DL_BYTE dlGetPixelValue (int x, int y) const
DL_BYTE dlGetPixelValue (const DLPoint &p) const
DLImageStats dlGetStats () const
DL_BYTEdlGetImageData () const
DL_BYTEdlGetSafeImageData () const
DLImage dlSubImage (int x, int y, int width, int height) const
DLImage dlSubImage (const DLZone &cropzone) const
DLImage dlSubImageMaxMassCC (int x, int y, int width, int height, float threshold=1.0) const
DLImage dlSubImageMaxDensityCC (int x, int y, int width, int height, float threshold=1.0) const
DLImage dlSubImageMaxHeightCC (int x, int y, int width, int height, float threshold=1.0) const
DLImage dlSubImageMaxWidthCC (int x, int y, int width, int height, float threshold=1.0) const
void dlSetPixel (int x, int y, DL_BYTE r, DL_BYTE g, DL_BYTE b)
void dlSetPixel (const DLPoint &p, DL_BYTE r, DL_BYTE g, DL_BYTE b)
void dlGetPixel (int x, int y, DL_BYTE &r, DL_BYTE &g, DL_BYTE &b) const
void dlGetPixel (const DLPoint &p, DL_BYTE &r, DL_BYTE &g, DL_BYTE &b) const
void dlSetPixel (int x, int y, DL_BYTE i)
void dlSetPixel (const DLPoint &p, DL_BYTE i)
DLImage dlCopyImage () const
bool dlIsGrayScaleBW () const
bool dlIsInside (const int x, const int y) const
bool dlIsInside (const DLPoint &p) const
DLImage dlPasteImage (DLImage &subImage, int xcoor, int ycoor) const
DLImage dlPasteImage (DLImage &subImage, const DLPoint &p) const
void dlPasteInImage (const DLImage &subImage, int xcoor, int ycoor)
void dlPasteInImage (const DLImage &subImage, const DLPoint &p)
DLImage dlAddImage (const DLImage &aImg, int xcoor, int ycoor) const
DLImage dlAddImage (const DLImage &aImg, const DLPoint &p) const
DLImage dlSubtractImage (const DLImage &aImg, int xcoor, int ycoor) const
DLImage dlSubtractImage (const DLImage &aImg, const DLPoint &p) const
DLImage dlResizeImage (int width, int height) const
DLImage dlResizeImage (double factor) const
DLImage dlRotateImage (double angle) const
DLImage dlFlipImage (DLFlipDirection direction) const
DLImage dlReverseImage () const
DLImage dlGetChannelImage (DLImage::DLColorChannels ch) const
DLImage dlGetChannelImage (int ch) const
DLImage dlConvertToYcrCb ()
DLImage dlConvertRGBToYCrCb () const
DLImage dlConvertYcrCbToRGB ()
DLImage dlConvertYCrCbToRGB () const
DLImage dlConvertRGBToHSV () const
DLImage dlConvertHSVToRGB () const
DLPoint dlCentroid () const
void setIsImageCorrupted (bool isCorrupted)
int dlGetImageBuffSize ()
bool isImageCorrupted ()
double dlRmax (bool flag) const
Tag List Functions
DLTagList::iterator dlGetTagListBegin ()
DLTagList::iterator dlGetTagListEnd ()
DLTagList::iterator dlFindTag (string tagKey)
void dlSetTag (string tagKey, string tagValue, bool overwriteEnabled=false)
void dlDeleteTag (string tagKey)
void dlClearTags ()
bool dlIsTagSet (string tagKey) const
bool dlIsTagListEmpty () const
string dlGetTag (string tagKey) const

Static Public Member Functions

static int dlGetTotalPages (void *pMemLoc, int nSize)
static int dlGetTotalPages (const char *filename)
static DLImage dlLoadImageAtPage (const char *filename, int pageNumber)
static DLImage dlLoadImageAtPage (const void *pMemLoc, int nSize, int pageNumber)
static DLImage dlMergeChannelImage (DLImage *im1, DLImage *im2, DLImage *im3)
static void RGBtoHSV (float r, float g, float b, float *h, float *s, float *v)
static void HSVtoRGB (float *r, float *g, float *b, float h, float s, float v)

Protected Attributes

DLImageHead imageHead
 Stores image header information.
unsigned char * imageData
 The image data buffer.
bool isOrgImgCorrupted

Detailed Description

The DLImage object is the entry point for performing image processing capabilities supported by DOCLIB.

It serves as the core for all future DOCLIB capabilites that will be hooked in. DLDocument and DLVideo classes will inherit the features of DLImage as they are developed.

An image in memory or on disk is read into DOCLIB's internal data format. All operations are performed on this format, completely independent of image type. The DLImage object is composed of the image header (see DLImageHead, which stores basic metadata such as height, width and resolution, as well as DLTagList, for storing user-defined metadata) and the image data itself (see dlGetSafeImageData() and dlGetImageData() for data access). The very easiest way to load an image and get started is:

 DLImage i("test.jpg");

Several basic image processing functions are included in the interface to DLImage. Certain other functions are implemented in other classes as static functions; see also DLBitsPerPixelConverter, DLSkeleton and DLSkew.

Definition at line 44 of file DLImage.h.


Member Enumeration Documentation

enum DLImage::DLFlipDirection

A selection of possible directions.

Enumerator:
DL_HORIZONTAL 
DL_VERTICAL 

Definition at line 158 of file DLImage.h.

enum DLImage::DLColorChannels

A selection of possible color channels

Enumerator:
DL_INVALID_CHANNEL 
DL_RED_CHANNEL 
DL_GREEN_CHANNEL 
DL_BLUE_CHANNEL 

Definition at line 166 of file DLImage.h.


Constructor & Destructor Documentation

DLImage::DLImage (  ) 

Default DLImage Constructor. Initializes image data to NULL.

DLImage::DLImage ( const DLImage orig  ) 

DLImage Copy Constructor.

Parameters:
orig DLImage to copy

DLImage::DLImage ( DL_BYTE data,
const DLImageHead imageHead 
)

DLImage Constructor: takes a image data pointer and an image info header.

Parameters:
data DL_BYTE pointer to image data. Caller will allocate this memory and pass the memory block to the constructor. DLImage will be responsible for freeing this memory.
imageHead image header information
Exceptions:
DL_NULL_POINTER_EXCEPTION when data is NULL

DLImage::DLImage ( int  w,
int  h,
DLImageHead::DLBitDepths  depth 
)

DLImage Constructor: creates an empty image (white background) with width, height, and depth header information. Memory for the image data will be allocated.

Parameters:
w width of image
h height of image
depth Number of bits per image pixel; can be one of:

DLImage::DLImage ( int  w,
int  h,
int  depth 
)

DLImage Constructor: creates an empty image (white background) with width, height, and depth header information. Memory for the image data will be allocated.

Parameters:
w width of image
h height of image
depth Number of bits per image pixel; can be one of:
Deprecated:
Use DLImage (int w, int h, DLImageHead::DLBitDepths depth) instead
This is in Phase One of the Documented Deprecation Process

DLImage::DLImage ( const char *  filename,
DLBaseImage imageType = NULL 
)

DLImage Constructor: Loads an image from a file. If the image file format is known, a pointer to one of the image format objects (see DLBaseImage) can be passed in; however, if the second parameter is not used, DOCLIB will try and open using all format types. If an image is not recognized by any of DOCLIB's supported types, an exception will be thrown. Note that each image format object provides a function createImageReader() which returns a handle of and image format object. Also, for convenience, globally-accessible handle variables are provided for each format. These are:

Here are examples of each loading method:
 DLImage i1("test.jpg"); // load an image; DOCLIB determines file format
 DLImage i2("image2", dlPngProcessor); // force DOCLIB to load as PNG
 DLImage i3("image2", DLPNGImage::createImageReader()); // force DOCLIB to load as PNG
Parameters:
filename name of file to open
imageType (optional) handle of an image format object

DLImage::DLImage ( const void *  pMemLoc,
int  nSize,
DLBaseImage imageType = NULL 
)

DLImage Constructor: Load an image from a memory block. The memory block must be the memory image of an image file in one of the file formats supported by DOCLIB. If the image file format is known, a pointer to one of the image format objects (see DLBaseImage) can be passed in; however, if the second parameter is not used, DOCLIB will try and open using all format types. If an image is not recognized by any of DOCLIB's supported types, an exception will be thrown.

Parameters:
pMemLoc pointer to beginning of memory block
nSize size of the memory block in bytes
imageType (optional) pointer to image format object

virtual DLImage::~DLImage (  )  [virtual]

Default DLImage Destructor. Deletes image data and reference.


Member Function Documentation

DLImage& DLImage::operator= ( const DLImage image  ) 

Assignment operator: make a copy of an image.

 DLImage i("test.jpg");
 DLImage j = i; // copy image \c i to image \c j
Exceptions:
DL_MEMORY_EXCEPTION when a self assignment is attempted

void DLImage::dlLoadImage ( const char *  filename,
DLBaseImage imageType = NULL 
)

Opens an image written to disk. If the image file format is known, a pointer to one of the image format objects (see DLBaseImage) can be passed in; however, if the second parameter is not used, DOCLIB will try and open using all format types. If an image is not recognized by any of DOCLIB's supported types, an exception will be thrown.

Parameters:
filename name of file to open
imageType (optional) pointer to image format object

void DLImage::dlLoadImage ( const void *  pMemLoc,
const int  nSize,
DLBaseImage imageType = NULL 
)

Opens an image from memory. The memory block must be the memory image of an image file in one of the file formats supported by DOCLIB. If the image file format is known, a pointer to one of the image format objects (see DLBaseImage) can be passed in; however, if the second parameter is not used, DOCLIB will try and open using all format types. If an image is not recognized by any of DOCLIB's supported types, an exception will be thrown.

Parameters:
pMemLoc pointer to beginning of memory block
nSize size of the memory block in bytes
imageType (optional) pointer to image format object

static int DLImage::dlGetTotalPages ( void *  pMemLoc,
int  nSize 
) [static]

Returns the number of pages contained in an image file stored in a memory block. It makes use of the DLImageFactory to determine the image type and then calls the dlGetTotalPages() function for the particular image object.

Parameters:
pMemLoc pointer to beginning of memory block
nSize size of memory buffer in bytes
Returns:
the number of pages in the image

static int DLImage::dlGetTotalPages ( const char *  filename  )  [static]

Returns the number of pages contained in an image file. It make use of the DLImageFactory to determine the image type and then calls the dlGetTotalPages() function for the particular image object.

Parameters:
filename filename of image file
Returns:
the number of pages in the image

static DLImage DLImage::dlLoadImageAtPage ( const char *  filename,
int  pageNumber 
) [static]

Loads a particular page of a multiple page image file.

Parameters:
filename name of image file to be opened
pageNumber number of page to be opened
Returns:
image of page

static DLImage DLImage::dlLoadImageAtPage ( const void *  pMemLoc,
int  nSize,
int  pageNumber 
) [static]

Loads a particular page of a multiple page image file stored in a memory buffer.

Parameters:
pMemLoc pointer to beginning of memory Image buffer to be opened
nSize size of buffer in bytes
pageNumber number of page to be opened
Returns:
image of page

void DLImage::dlSaveImage ( const char *  filename,
DLBaseImage imageType = NULL 
) const

Save an image.

DOCLIB will determine the image format to save to by the extension of filename. To override this choice, or if the filename does not have a valid extension, you may indicate the image format to use by passing in a pointer to one of the image format objects (see DLBaseImage). Example:

 DLImage i("test.jpg");
 // ... processing
 i.dlSaveImage("out.jpg"); // save as JPEG automatically
 i.dlSaveImage("output.file", DLTIFFImage::createImageReader()); // save as TIFF
 i.dlSaveImage("output.file", dlTiffProcessor); // save as TIFF
Parameters:
filename full path on disk to save file (e.g. "/home/joe/tree.tif")
imageType (optional) pointer to image format object
Exceptions:
DL_NULL_POINTER_EXCEPTION when data is NULL

void* DLImage::dlSaveImageToMem ( int &  nSize,
DLBaseImage imageType 
) const

Save an image to memory.

You must indicate the image format to use by passing in a pointer to one of the image format objects (see DLBaseImage). Example:

 DLImage i("test.jpg");
 DL_BYTE *buff;
 int size;
 // ... processing
 buff = (DL_BYTE *) i.dlSaveImageToMem(size, DLTIFFImage::createImageReader()); // save as TIFF
 buff = (DL_BYTE *) i.dlSaveImageToMem(size, dlTiffProcessor); // save as TIFF
Parameters:
[out] nSize this is where the buffer length will be returned)
[in] imageType pointer to image format object
Exceptions:
DL_NOT_SUPPORTED_EXCEPTION Not all Image Types support writing to memory. Currently supported types are: TIFF, PBM, BMP, JPG
Returns:
pointer to memory buffer in which the image was saved
Exceptions:
DL_NULL_POINTER_EXCEPTION when data is NULL

DLImageHead DLImage::dlGetImageHead (  )  const

Returns:
DLImageHead object, containing the image header information.

int DLImage::dlGetWidth (  )  const [inline]

Get the image width

Returns:
image width

Definition at line 305 of file DLImage.h.

References imageHead, and DLImageHead::width.

Referenced by DLPage::dlGetPageWidth().

int DLImage::dlGetHeight (  )  const [inline]

Get the image height

Returns:
image height

Definition at line 311 of file DLImage.h.

References DLImageHead::height, and imageHead.

Referenced by dlGetImageBuffSize(), and DLPage::dlGetPageHeight().

int DLImage::dlGetChannels (  )  const [inline]

Get the number of image data channels; usually 3 for 24-bit color RGB images, and 1 for binary, grayscale or palettized images.

Returns:
image channels

Definition at line 318 of file DLImage.h.

References DLImageHead::channels, and imageHead.

DLImageHead::DLBitDepths DLImage::dlGetDepth (  )  const [inline]

Get the number of bits per image pixel; can be one of:

Returns:
image bit depth

Definition at line 329 of file DLImage.h.

References DLImageHead::depth, and imageHead.

DLColor::DLColorTypes DLImage::dlGetColorModel (  )  const [inline]

Get the image color model; can be one of:

Returns:
image color model

Definition at line 342 of file DLImage.h.

References DLImageHead::colorModel, and imageHead.

int DLImage::dlGetDataOrder (  )  const [inline]

Get data order: not currently used.

Returns:
data order

Definition at line 348 of file DLImage.h.

References DLImageHead::dataOrder, and imageHead.

int DLImage::dlGetRowSize (  )  const [inline]

Get the image row size: the number of bytes needed to store the raw data of a single row of this image. (Image data in DOCLIB is stored in row-major format.)

Returns:
row size

Definition at line 356 of file DLImage.h.

References imageHead, and DLImageHead::rowSize.

Referenced by dlGetImageBuffSize().

DLImageHead::DLDataAlignments DLImage::dlGetDataAlignment (  )  const [inline]

Get data alignment. Can be

Returns:
data alignment

Definition at line 367 of file DLImage.h.

References DLImageHead::dataAlignment, and imageHead.

float DLImage::dlGetHorizontalResolution (  )  const [inline]

Get resolution (horizontal).

See also:
dlGetResolutionFlag() for determining the unit of measure.
Returns:
horizontal image resolution

Definition at line 374 of file DLImage.h.

References DLImageHead::horizontalResolution, and imageHead.

float DLImage::dlGetVerticalResolution (  )  const [inline]

Get resolution (vertical)

See also:
dlGetResolutionFlag() for determining the unit of measure.
Returns:
vertical image resolution

Definition at line 381 of file DLImage.h.

References imageHead, and DLImageHead::verticalResolution.

bool DLImage::dlGetResolutionFlag (  )  const [inline]

Get image resolution flag. Upon opening an image of any format containing resolution information, DOCLIB automatically converts the resolution to dots-per-inch (or unitless, if the image does not indicate the units used).

Returns:
resolution flag:
  • true resolution in dots-per-inch (dpi)
  • false unitless

Definition at line 392 of file DLImage.h.

References imageHead, and DLImageHead::resolutionFlag.

void DLImage::dlSetHorizontalResolution ( int  resolution  )  [inline]

Set image resolution (horizontal).

See also:
dlSetResolutionFlag() for setting the resolution units of measure.
Parameters:
resolution image resolution

Definition at line 400 of file DLImage.h.

References DLImageHead::horizontalResolution, and imageHead.

void DLImage::dlSetVerticalResolution ( int  resolution  )  [inline]

Set image resolution (vertical).

See also:
dlSetResolutionFlag() for setting the resolution units of measure.
Parameters:
resolution image resolution

Definition at line 407 of file DLImage.h.

References imageHead, and DLImageHead::verticalResolution.

void DLImage::dlSetHorizontalResolution ( float  resolution  )  [inline]

Set image resolution (horizontal).

See also:
dlSetResolutionFlag() for setting the resolution units of measure.
Parameters:
resolution image resolution

Definition at line 414 of file DLImage.h.

References DLImageHead::horizontalResolution, and imageHead.

void DLImage::dlSetVerticalResolution ( float  resolution  )  [inline]

Set image resolution (vertical).

See also:
dlSetResolutionFlag() for setting the resolution units of measure.
Parameters:
resolution image resolution

Definition at line 421 of file DLImage.h.

References imageHead, and DLImageHead::verticalResolution.

void DLImage::dlSetResolutionFlag ( bool  resflag  )  [inline]

Set image resolution units of measure.

Note:
Changing the resolution units of measure will not automatically convert the previously-stored resolution values.
Parameters:
resflag resolution flag
  • true = dpi
  • false = unitless

Definition at line 431 of file DLImage.h.

References imageHead, and DLImageHead::resolutionFlag.

DL_BYTE DLImage::dlGetPixelValue ( int  x,
int  y 
) const

Get the pixel value of a binary or grayscale image. For a binary image, this will be either DL_WHITE or DL_BLACK. For a grayscale image, this will range from 0 to 255, with 0 being black and 255 being white.

Parameters:
x column, or x-coordinate of requested pixel
y row, or y-coordinate of requested pixel
Returns:
DL_BYTE value of requested pixel.
Exceptions:
DL_WRONG_FORMAT_EXCEPTION When Image is not a Gray or BW Image
DL_WRONG_FORMAT_EXCEPTION When (x,y) is out of bounds
DL_NULL_POINTER_EXCEPTION When image data is NULL

Referenced by dlGetPixelValue().

DL_BYTE DLImage::dlGetPixelValue ( const DLPoint p  )  const [inline]

Get the pixel value of a binary or grayscale image. For a binary image, this will be either DL_WHITE or DL_BLACK. For a grayscale image, this will range from 0 to 255, with 0 being black and 255 being white.

Parameters:
p DLPoint containing x,y coordinates of requested pixel
Returns:
DL_BYTE value of requested pixel.
Exceptions:
DL_WRONG_FORMAT_EXCEPTION When Image is not a Gray or BW Image
DL_WRONG_FORMAT_EXCEPTION When (x,y) is out of bounds
DL_NULL_POINTER_EXCEPTION When image data is NULL

Definition at line 458 of file DLImage.h.

References dlGetPixelValue(), DLPoint::x, and DLPoint::y.

DLImageStats DLImage::dlGetStats (  )  const

Get image statistics, such as mean and standard deviation of pixel values.

Returns:
DLImageStats object containing the statistics.

DL_BYTE* DLImage::dlGetImageData (  )  const [inline]

Get a pointer to the raw image data. When writing a new DOCLIB image processing application, this is the most efficient way to access and modify the internal pixel data. See also dlGetPixelValue() for an easier, but possibly less efficient way of accessing a pixel's value.

The DOCLIB data layout is row-major; all the data for a single row of the image is in a contiguous memory block, followed by the data for the next row. Use the functions dlGetDepth(), dlGetColorModel() and dlGetRowSize() to determine the storage format and storage size for each pixel as well as the number of bytes required for each row of the image.

Binary images will be stored one bit per pixel, with the leftmost pixel occupying the most significant bit (MSB) and the rightmost pixel occupying the least significant bit (LSB). A mask may be used * to access individual pixel values this way. This statement:

 DL_BYTE getmask[8] = {128,64,32,16,8,4,2,1};
sets up an array of masks; each entry in the array contains a mask with a 1 in one bit position and 0's in the other seven. mask[0] is used to access the leftmost bit and mask[7] is used to access the rightmost bit. To get a pixel value, AND the byte with the appropriate mask. If the result is zero, then the pixel was off (black). If the result is non-zero, the pixel was on (white).
 DL_BYTE result = imageData[k] & mask[2]; // check third pixel
To set a pixel to 0 (black), AND the byte of image data with the one's complement (inverse) of the appropriate mask.
 imageData[k] &= ~(mask[2]);
To set a pixel to 1 (white), OR the byte of image data with the appropriate mask.
 imageData[k] |= mask[2];
If the width of a binary image is not divisible by 8, the last byte in a row's data will contain pixel data in the most significant bits. The next row will begin with a new byte; that is, rows only change on byte boundaries.

Grayscale images are stored one byte per pixel, with 0x00 as black, and 0xFF (255) as white.

RGB color images are stored 3 consecutive bytes per pixel, in single plane format. (As opposed to separate plane format; if an image file is stored in separate plane format, DOCLIB converts the image to single-plane in its internal data.) The first byte is the red value, the second byte is the green value, and the third byte is the blue value.

Be mindful of changing the returned data as it will also change the value of the data that is a part of DLImage. If you don't want to modify the data, consider using dlGetSafeImageData() which will return a copy of the data.

Returns:
image data

Definition at line 526 of file DLImage.h.

References imageData.

DL_BYTE* DLImage::dlGetSafeImageData (  )  const

Get the raw image data. Returns a copy of the raw data to ensure that the contents in DLImage is not modified. Note, however, the impact using this function may have on performance. For time critical applications consider developing using this function and using the dlGetImageData function before release. See dlGetImageData() for a descripition of the DOCLIB internal data format.

Returns:
image data
Exceptions:
DL_NULL_POINTER_EXCEPTION When data is NULL
DL_MEMORY_EXCEPTION When unable to allocate enough memory for data buffer

DLImage DLImage::dlSubImage ( int  x,
int  y,
int  width,
int  height 
) const

Extract a region of the image (crop).

Parameters:
x column (x-coordinate) of upper-left point of region to extract
y row (y-coordinate) of upper-left point of region to extract
width width of region to extract
height height of region to extract
Returns:
extracted sub-image
Exceptions:
DL_NULL_POINTER_EXCEPTION When image data is NULL
DL_WRONG_FORMAT_EXCEPTION When the subimage is out of bounds
DL_NOT_SUPPORTED_EXCEPTION When image is not 1, 8 or 24 bits.

DLImage DLImage::dlSubImage ( const DLZone cropzone  )  const

Extract a region of the image (crop).

Parameters:
cropzone DLZone with stats (origin, width, height) of region to extract
Returns:
extracted sub-image
Exceptions:
DL_NULL_POINTER_EXCEPTION When image data is NULL
DL_WRONG_FORMAT_EXCEPTION When the subimage is out of bounds
DL_NOT_SUPPORTED_EXCEPTION When image is not 1, 8 or 24 bits.

DLImage DLImage::dlSubImageMaxMassCC ( int  x,
int  y,
int  width,
int  height,
float  threshold = 1.0 
) const

Extract a region of the image (crop), perserving only those connected components with an mass greater than or equal to the maximum mass * threshold

Parameters:
x column (x-coordinate) of upper-left point of region to extract
y row (y-coordinate) of upper-left point of region to extract
width width of region to extract
height height of region to extract
threshold threshold percentage whereby components less than threshold * max_mass will be filtered.
Returns:
extracted sub-image

DLImage DLImage::dlSubImageMaxDensityCC ( int  x,
int  y,
int  width,
int  height,
float  threshold = 1.0 
) const

Extract a region of the image (crop), perserving only those connected components with an density greater than or equal to the maximum density * threshold

Parameters:
x column (x-coordinate) of upper-left point of region to extract
y row (y-coordinate) of upper-left point of region to extract
width width of region to extract
height height of region to extract
threshold threshold percentage whereby components less than threshold * max_density will be filtered.
Returns:
extracted sub-image

DLImage DLImage::dlSubImageMaxHeightCC ( int  x,
int  y,
int  width,
int  height,
float  threshold = 1.0 
) const

Extract a region of the image (crop), perserving only those connected components with a Height greater than or equal to the maximum Height * threshold

Parameters:
x column (x-coordinate) of upper-left point of region to extract
y row (y-coordinate) of upper-left point of region to extract
width width of region to extract
height height of region to extract
threshold threshold percentage whereby components less than threshold * max_Height will be filtered.
Returns:
extracted sub-image

DLImage DLImage::dlSubImageMaxWidthCC ( int  x,
int  y,
int  width,
int  height,
float  threshold = 1.0 
) const

Extract a region of the image (crop), perserving only those connected components with a Width greater than or equal to the maximum Width * threshold

Parameters:
x column (x-coordinate) of upper-left point of region to extract
y row (y-coordinate) of upper-left point of region to extract
width width of region to extract
height height of region to extract
threshold threshold percentage whereby components less than threshold * max_Width will be filtered.
Returns:
extracted sub-image

void DLImage::dlSetPixel ( int  x,
int  y,
DL_BYTE  r,
DL_BYTE  g,
DL_BYTE  b 
)

Set a pixel in the image to a given color

Parameters:
x column (x-coordinate) of point
y row (y-coordinate) of point
r red value
g green value
b blue value
Exceptions:
DL_WRONG_FORMAT_EXCEPTION When Image is not a Color Image
DL_WRONG_FORMAT_EXCEPTION When (x,y) is out of bounds
DL_NULL_POINTER_EXCEPTION When image data is NULL

Referenced by dlSetPixel().

void DLImage::dlSetPixel ( const DLPoint p,
DL_BYTE  r,
DL_BYTE  g,
DL_BYTE  b 
) [inline]

Set a pixel in an image to a given color.

Parameters:
p DLPoint containing x,y coordinates
r red value
g green value
b blue value
Exceptions:
DL_WRONG_FORMAT_EXCEPTION When Image is not a Color Image
DL_WRONG_FORMAT_EXCEPTION When (x,y) is out of bounds
DL_NULL_POINTER_EXCEPTION When image data is NULL

Definition at line 633 of file DLImage.h.

References dlSetPixel(), DLPoint::x, and DLPoint::y.

void DLImage::dlGetPixel ( int  x,
int  y,
DL_BYTE r,
DL_BYTE g,
DL_BYTE b 
) const

Get the value of a pixel in an RGB color image.

Parameters:
[in] x column (x-coordinate) of point
[in] y row (y-coordinate) of point
[out] r red value
[out] g green value
[out] b blue value
Exceptions:
DL_WRONG_FORMAT_EXCEPTION When Image is not a Color Image
DL_WRONG_FORMAT_EXCEPTION When (x,y) is out of bounds
DL_NULL_POINTER_EXCEPTION When image data is NULL

Referenced by dlGetPixel().

void DLImage::dlGetPixel ( const DLPoint p,
DL_BYTE r,
DL_BYTE g,
DL_BYTE b 
) const [inline]

Get the value of a pixel in an RGB color image.

Parameters:
[in] p DLPoint containing x,y coordinates
[out] r red value
[out] g green value
[out] b blue value
Exceptions:
DL_WRONG_FORMAT_EXCEPTION When Image is not a Color Image
DL_WRONG_FORMAT_EXCEPTION When (x,y) is out of bounds
DL_NULL_POINTER_EXCEPTION When image data is NULL

Definition at line 659 of file DLImage.h.

References dlGetPixel(), DLPoint::x, and DLPoint::y.

void DLImage::dlSetPixel ( int  x,
int  y,
DL_BYTE  i 
)

Set a pixel in an image to a given grayscale value.

Parameters:
[in] x column (x-coordinate) of point
[in] y row (y-coordinate) of point
i grayscale value
Exceptions:
DL_WRONG_FORMAT_EXCEPTION When Image is not a Gray or BW Image
DL_WRONG_FORMAT_EXCEPTION When (x,y) is out of bounds
DL_NULL_POINTER_EXCEPTION When image data is NULL

void DLImage::dlSetPixel ( const DLPoint p,
DL_BYTE  i 
) [inline]

Set a pixel in an image to a given grayscale value.

Parameters:
p DLPoint containing x,y coordinates
i grayscale value
Exceptions:
DL_WRONG_FORMAT_EXCEPTION When Image is not a Gray or BW Image
DL_WRONG_FORMAT_EXCEPTION When (x,y) is out of bounds
DL_NULL_POINTER_EXCEPTION When image data is NULL

Definition at line 681 of file DLImage.h.

References dlSetPixel(), DLPoint::x, and DLPoint::y.

DLImage DLImage::dlCopyImage (  )  const

Copy image

Returns:
copied image

bool DLImage::dlIsGrayScaleBW (  )  const

Checks to see if a grayscale image has only black or white values

Returns:
true if a BW image; false if intermediate grayscale values are present

bool DLImage::dlIsInside ( const int  x,
const int  y 
) const

Check if a point is inside this image.

Parameters:
x column of point
y row of point
Returns:
true if it is

Referenced by dlIsInside().

bool DLImage::dlIsInside ( const DLPoint p  )  const [inline]

Check if a point is inside this image.

Parameters:
p DLPoint containing pixel x,y coordinates
Returns:
true if it is

Definition at line 710 of file DLImage.h.

References dlIsInside(), DLPoint::x, and DLPoint::y.

DLImage DLImage::dlPasteImage ( DLImage subImage,
int  xcoor,
int  ycoor 
) const

Paste an image onto the current image. This function returns a new image with the pasted region; to write to the current image, see dlPasteInImage().

Parameters:
subImage source image to be pasted
xcoor column (x-coordinate) of destination image to paste to
ycoor row (y-coordinate) of destination image to paste to
Returns:
DLImage new image with pasted region

Referenced by dlPasteImage().

DLImage DLImage::dlPasteImage ( DLImage subImage,
const DLPoint p 
) const [inline]

Paste an image onto the current image. This function returns a new image with the pasted region; to write to the current image, see dlPasteInImage().

Parameters:
subImage source image to be pasted
p DLPoint containing pixel x,y coordinates of destination image to paste to
Returns:
DLImage new image with pasted region

Definition at line 732 of file DLImage.h.

References dlPasteImage(), DLPoint::x, and DLPoint::y.

void DLImage::dlPasteInImage ( const DLImage subImage,
int  xcoor,
int  ycoor 
)

Paste an image onto the current image; will modify the current image data. There will be no return value since the image data is being modified. See also dlPasteImage().

Parameters:
subImage source mage to be pasted
xcoor column (x-coordinate) of destination image to paste to
ycoor row (y-coordinate) of destination image to paste to

Referenced by dlPasteInImage().

void DLImage::dlPasteInImage ( const DLImage subImage,
const DLPoint p 
) [inline]

Paste an image onto the current image; will modify the current image data. There will be no return value since the image data is being modified. See also dlPasteImage().

Parameters:
subImage source mage to be pasted
p DLPoint containing pixel x,y coordinates of destination image to paste to

Definition at line 754 of file DLImage.h.

References dlPasteInImage(), DLPoint::x, and DLPoint::y.

DLImage DLImage::dlAddImage ( const DLImage aImg,
int  xcoor,
int  ycoor 
) const

Add an image into the current image. Note: At this time, pixel values that exceed the maximum will overflow and not be capped at 255.

Parameters:
aImg image to be added
xcoor column (x-coordinate) of destination image
ycoor row (y-coordinate) of destination image
Returns:
DLImage image with added region

Referenced by dlAddImage().

DLImage DLImage::dlAddImage ( const DLImage aImg,
const DLPoint p 
) const [inline]

Add an image into the current image. Note: At this time, pixel values that exceed the maximum will overflow and not be capped at 255.

Parameters:
aImg image to be added
p DLPoint containing pixel x,y coordinates of destination image
Returns:
DLImage image with added region

Definition at line 776 of file DLImage.h.

References dlAddImage(), DLPoint::x, and DLPoint::y.

DLImage DLImage::dlSubtractImage ( const DLImage aImg,
int  xcoor,
int  ycoor 
) const

Subtract an image from the current image

Parameters:
aImg image to be subtracted
xcoor column (x-coordinate) of destination image
ycoor row (y-coordinate) of destination image
Returns:
DLImage image with subtracted region

Referenced by dlSubtractImage().

DLImage DLImage::dlSubtractImage ( const DLImage aImg,
const DLPoint p 
) const [inline]

Subtract an image from the current image

Parameters:
aImg image to be subtracted
p DLPoint containing pixel x,y coordinates of destination image
Returns:
DLImage image with subtracted region

Definition at line 794 of file DLImage.h.

References dlSubtractImage(), DLPoint::x, and DLPoint::y.

DLImage DLImage::dlResizeImage ( int  width,
int  height 
) const

Scale image to specified height and width

Parameters:
width scaled image width
height scaled image height
Returns:
scaled image
Exceptions:
DL_NULL_POINTER_EXCEPTION When image data is NULL
DL_NOT_SUPPORTED_EXCEPTION When width or height are less than 0
DL_NOT_SUPPORTED_EXCEPTION When image is not 1, 8 or 24 bits.

DLImage DLImage::dlResizeImage ( double  factor  )  const

Scale image by a factor

Parameters:
factor scale factor (e.g. 1.0 keeps the image the same, 0.5 makes the new image half the size; 2.0 doubles the size of the image)
Returns:
scaled image
Exceptions:
DL_NULL_POINTER_EXCEPTION When image data is NULL
DL_NOT_SUPPORTED_EXCEPTION When factor is less than 0
DL_NOT_SUPPORTED_EXCEPTION When image is not 1, 8 or 24 bits.

DLImage DLImage::dlRotateImage ( double  angle  )  const

Rotate image

Parameters:
angle angle to rotate image by (in degrees). The sign of angle controls direction of rotation: positive angle - clockwise, negative - counterclockwise
Returns:
rotated image in its original bits-per-pixel representation
Exceptions:
DL_NULL_POINTER_EXCEPTION When image data is NULL
DL_NOT_SUPPORTED_EXCEPTION When image is not 1, 8 or 24 bits.

DLImage DLImage::dlFlipImage ( DLFlipDirection  direction  )  const

Flip image

Parameters:
direction direction to flip the image: can be one of
Returns:
flipped image

DLImage DLImage::dlReverseImage (  )  const

Reverse Image

Returns:
DLImage of reversed image

DLImage DLImage::dlGetChannelImage ( DLImage::DLColorChannels  ch  )  const

Get a one channel image from a color image. The image returned uses one byte per pixel and behaves as a grayscale image.

Parameters:
ch number of channel to be returned:
Returns:
channel image

DLImage DLImage::dlGetChannelImage ( int  ch  )  const

Get a one channel image from a color image. The image returned uses one byte per pixel and behaves as a grayscale image.

Parameters:
ch number of channel to be returned:
  • 0 red channel
  • 1 green channel
  • 2 blue channel
Returns:
channel image
Deprecated:
Use DLImage::dlGetChannelImage (DLImage::DLColorChannels ch) instead
This is in Phase One of the Documented Deprecation Process

static DLImage DLImage::dlMergeChannelImage ( DLImage im1,
DLImage im2,
DLImage im3 
) [static]

Get an RGB color image from three one-byte-per-pixel channel images. Example:

 DLImage redim, blueim, greenim;
 // ... processing
 DLImage colorimage = DLImage::dlMergeChannelImage(&redim, &greenim, &blueim);
Parameters:
[in] im1 red channel image
[in] im2 green channel image
[in] im3 blue channel image
Returns:
full color image

DLImage DLImage::dlConvertToYcrCb (  ) 

Convert DLImage to the YCrCb colorspace from RGB. The Y (brightness), Cr (red chrominance), and Cb (blue chrominance) values are calculated from the R, G, and B values of a pixel as follows:

\[ \left[ \begin{array}{l} Y \\ Cr \\ Cb \end{array} \right] = \left[ \begin{array}{rrrr} 0.257 & 0.504 & 0.098 & 16 \\ 0.439 &-0.368 &-0.071 & 128 \\ -0.148 &-0.291 & 0.439 & 128 \end{array} \right] \left[ \begin{array}{l} R \\ G \\ B \\ 1 \end{array} \right] \]

Note that the header of the image returned (see DLImageHead::colorModel) will still indicate the original image's colorspace, and will not be modified to reflect that the updated pixel values are in the YCrCb colorspace, nor will it be checked to verify that the original image did in fact use the RGB colorspace.

This function is in Stage One of the documented Three Stage Deprecation Process

Returns:
YCrCb image
Deprecated:
Use DLImage::dlConvertRGBToYCrCb() instead.
This is in Phase Two of the Documented Deprecation Process

DLImage DLImage::dlConvertRGBToYCrCb (  )  const

Convert DLImage to the YCrCb colorspace from RGB. The Y (brightness), Cr (red chrominance), and Cb (blue chrominance) values are calculated from the R, G, and B values of a pixel as follows:

\[ \left[ \begin{array}{l} Y \\ Cr \\ Cb \end{array} \right] = \left[ \begin{array}{rrrr} 0.257 & 0.504 & 0.098 & 16 \\ 0.439 &-0.368 &-0.071 & 128 \\ -0.148 &-0.291 & 0.439 & 128 \end{array} \right] \left[ \begin{array}{l} R \\ G \\ B \\ 1 \end{array} \right] \]

Note that the header of the image returned (see DLImageHead::colorModel) will still indicate the original image's colorspace, and will not be modified to reflect that the updated pixel values are in the YCrCb colorspace, nor will it be checked to verify that the original image did in fact use the RGB colorspace.

Returns:
YCrCb image

DLImage DLImage::dlConvertYcrCbToRGB (  ) 

Convert DLImage to the RGB colorspace from YCrCb, using the following formulas:

\begin{eqnarray*} R &=& 1.164(Y - 16)+1.596(Cr - 128) \\ G &=& 1.164(Y - 16)-0.813(Cr - 128)-0.391(Cb - 128) \\ B &=& 1.164(Y - 16)+2.018(Cb - 128) \end{eqnarray*}

Note that the header of the image returned (see DLImageHead::colorModel) will still indicate the original image's colorspace, and will not be modified to reflect that the updated pixel values are in the RGB colorspace, nor will it be checked to verify that the original image did in fact use the YCrCb colorspace.

This function is in Stage One of the documented Three Stage Deprecation Process.

Returns:
DLImage RGB image
Deprecated:
Use DLImage::dlConvertYCrCbToRGB() instead.
This is in Phase Two of the Documented Deprecation Process

DLImage DLImage::dlConvertYCrCbToRGB (  )  const

Convert DLImage to the RGB colorspace from YCrCb, using the following formulas:

\begin{eqnarray*} R &=& 1.164(Y - 16)+1.596(Cr - 128) \\ G &=& 1.164(Y - 16)-0.813(Cr - 128)-0.391(Cb - 128) \\ B &=& 1.164(Y - 16)+2.018(Cb - 128) \end{eqnarray*}

Note that the header of the image returned (see DLImageHead::colorModel) will still indicate the original image's colorspace, and will not be modified to reflect that the updated pixel values are in the RGB colorspace, nor will it be checked to verify that the original image did in fact use the YCrCb colorspace.

Returns:
DLImage RGB image

DLImage DLImage::dlConvertRGBToHSV (  )  const

Convert DLImage from the RGB colorspace to the HSV colorspace. The H (hue), S (saturation) and V (value / brightness) are calculated for each pixel using the following formulas:

\begin{eqnarray*} H &=& 60 \times \left\{ \begin{array}{ll} \frac{G-B}{\max - \min}, & \max = R \\ 2 + \frac{B-R}{\max - \min} + 120, & \max = G \\ 4 + \frac{R-G}{\max - \min} + 240, & \max = B \end{array} \right. \\ S &=& \frac{\max - \min}{\max} \\ V &=& \max \end{eqnarray*}

where $\max = \max(R,G,B)$ and $\min = \min(R,G,B)$.

Note that the header of the image returned (see DLImageHead::colorModel) will still indicate the original image's colorspace, and will not be modified to reflect that the updated pixel values are in the HSV colorspace, nor will it be checked to verify that the original image did in fact use the RGB colorspace.

Returns:
HSV image

DLImage DLImage::dlConvertHSVToRGB (  )  const

Convert DLImage to the RGB colorspace from the HSV colorspace, using the following calculations:

\begin{eqnarray*} H_i &=& \left\lfloor \frac{H}{60} \right\rfloor \\ f &=& \frac{H}{60} - H_i \\ p &=& V(1-S) \\ q &=& V(1-fS) \\ t &=& V(1-(1-f)S) \end{eqnarray*}

\begin{eqnarray*} \mbox{if}\: H_i = 0 &\mbox{then}& R=V, G=t, B=p \\ \mbox{if}\: H_i = 1 &\mbox{then}& R=q, G=V, B=p \\ \mbox{if}\: H_i = 2 &\mbox{then}& R=p, G=V, B=t \\ \mbox{if}\: H_i = 3 &\mbox{then}& R=p, G=q, B=V \\ \mbox{if}\: H_i = 4 &\mbox{then}& R=t, G=p, B=V \\ \mbox{if}\: H_i = 5 &\mbox{then}& R=B, G=p, B=q \\ \end{eqnarray*}

Returns:
RGB image

DLPoint DLImage::dlCentroid (  )  const

Calculate the centroid of the image.

Returns:
centroid

void DLImage::setIsImageCorrupted ( bool  isCorrupted  ) 

Set Check if original image is corrupted

Parameters:
isCorrupted true: to indicate the image is corrupted. false: to indicate the image is not corrupted (Default).

DLTagList::iterator DLImage::dlGetTagListBegin (  )  [inline]

Obtain an iterator to the beginning of the image tag list. User-defined metadata may be stored in the DLTagList contained in the image's header. This set of functions is for setting and inspecting tags. Besides typical get and set functions, and iterator interface is provided for iterating over all the entries in the tag list. The iterators behave the same as typical STL iterators: dlGetTagListBegin() and dlGetTagListEnd() are used to generate the iterators for use in a for or while loop; the iterators can be incremented or decremented using ++ and --, and can be dereferenced using the * and arrow operators. Dereferencing an iterator produces a pair<string,string> where the first element is the tag key, and the second element is the tag value.

 DLImage i("test.jpg");
 DLTagList::iterator ii;
 for (ii = i.dlGetTagListBegin(); ii != i.dlGetTagListEnd(); ii++) {
   cout << "tag key: " << ii->first << " tag value: " << ii->second << endl;
 }

Definition at line 1187 of file DLImage.h.

References DLTagList::begin(), imageHead, and DLImageHead::imageTags.

DLTagList::iterator DLImage::dlGetTagListEnd (  )  [inline]

Obtain an iterator pointing just past the end of the image tag list. The end iterator is typically used in a for loop for bounds checking. Warning: actually dereferencing the end iterator is undefined, and will likely cause your program to crash.

Definition at line 1195 of file DLImage.h.

References DLTagList::end(), imageHead, and DLImageHead::imageTags.

DLTagList::iterator DLImage::dlFindTag ( string  tagKey  )  [inline]

Get an iterator pointing to the location of tagKey in the map

Returns:
iterator

Definition at line 1201 of file DLImage.h.

References DLTagList::dlFindTag(), imageHead, and DLImageHead::imageTags.

void DLImage::dlSetTag ( string  tagKey,
string  tagValue,
bool  overwriteEnabled = false 
)

Set an image tag. If a tag with the specified key already exists in this image, it will not be overwritten unless the optional parameter overwriteEnabled is set to true.

Parameters:
tagKey key of the image tag
tagValue value of the image tag
overwriteEnabled option for overwriting existing field (default is false )
Exceptions:
DL_Exception DL_UNKNOWN_TAG_EXCEPTION

void DLImage::dlDeleteTag ( string  tagKey  ) 

Remove the tag with the specified key from the list of image tags

Parameters:
tagKey key of the image tag

void DLImage::dlClearTags (  )  [inline]

Erase all the existing image tags

Definition at line 1223 of file DLImage.h.

References DLTagList::dlClearTags(), imageHead, and DLImageHead::imageTags.

bool DLImage::dlIsTagSet ( string  tagKey  )  const

Check whether a document tag with the given key exists

Parameters:
tagKey key of the document tag
Returns:
true if a tag exists with that key

bool DLImage::dlIsTagListEmpty (  )  const [inline]

Check whether the whole image tag list is empty

Returns:
true if the tag list is empty

Definition at line 1236 of file DLImage.h.

References DLTagList::dlIsTagListEmpty(), imageHead, and DLImageHead::imageTags.

string DLImage::dlGetTag ( string  tagKey  )  const

Get the field value of a specified image tag

Parameters:
tagKey image tag key

int DLImage::dlGetImageBuffSize (  )  [inline]

Get the total number of bytes in the image

Returns:
the number of bytes in the image.

Definition at line 1249 of file DLImage.h.

References dlGetHeight(), and dlGetRowSize().

bool DLImage::isImageCorrupted (  ) 

Indicates if the image was considered corrupted upon loading. Each image object will have it’s own error recovery/correction algorithm when loading an image. Look at image objects for more details.

Returns:
bool

static void DLImage::RGBtoHSV ( float  r,
float  g,
float  b,
float *  h,
float *  s,
float *  v 
) [static]

Convert a given RGB triple to the HSV color space

Parameters:
[in] r R value
[in] g G value
[in] b B value
[out] h H value to be converted to
[out] s S value to be converted to
[out] v v value to be converted to

static void DLImage::HSVtoRGB ( float *  r,
float *  g,
float *  b,
float  h,
float  s,
float  v 
) [static]

Convert a given HSV triple to the RGB color space

Parameters:
[in] h H value
[in] s S value
[in] v v value
[out] r R value to be converted to
[out] g G value to be converted to
[out] b B value to be converted to

double DLImage::dlRmax ( bool  flag  )  const

Calculate the maximum within-image distance from centroid of a full image.

Parameters:
flag Can be either:
  • true to calculate the farthest image corner
  • false to calculate the farthest non-white pixel
Returns:
maximum distance


Member Data Documentation

DLImageHead DLImage::imageHead [protected]

Stores image header information.

Definition at line 1418 of file DLImage.h.

Referenced by dlClearTags(), dlFindTag(), dlGetChannels(), dlGetColorModel(), dlGetDataAlignment(), dlGetDataOrder(), dlGetDepth(), dlGetHeight(), dlGetHorizontalResolution(), dlGetResolutionFlag(), dlGetRowSize(), dlGetTagListBegin(), dlGetTagListEnd(), dlGetVerticalResolution(), dlGetWidth(), dlIsTagListEmpty(), dlSetHorizontalResolution(), dlSetResolutionFlag(), and dlSetVerticalResolution().

unsigned char* DLImage::imageData [protected]

The image data buffer.

Definition at line 1421 of file DLImage.h.

Referenced by dlGetImageData().

bool DLImage::isOrgImgCorrupted [protected]

Flag: indicates if the image was considered corrupted upon loading. Each image object will have it’s own error recovery/correction algorithm when loading an image. Can be checked with isImageCorrupted().

Definition at line 1427 of file DLImage.h.


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

DOCLIB is being developed under contract by a collaboration between:
The Laboratory for Language and Media Processing
Unviersity of Maryland, College Park
and
Booz | Allen | Hamilton

All Rights Reserved, 2003-2007