CDibImage v1.0

Welcome to CDibImage v1.0, A 32 bit MFC class to encapsulate Device Independent Bitmaps (DIB). Some of the features it include:

• Support for loading from file, resource and global memory.
• Working area support including a user extensible architecture.
• Comprehensive filter matrices including 3*3, 5*5 and 7*7.
• User defined filter support.
• Comprehensive undo and redo support including end user adjustment of levels and description strings.
• Built in functions to convert between the RGB and HSL colour spaces.
• Full file save support.
• Full clipboard support
• Comprehensive collection of image processing functions including brightness, contrast, gamma, HSL, blur, edge, noise, RGB, mirror, negate and greyscale plus many others.
• Selection of histogram & channel functions
• Single function support for GDI drawing & printing.
• Includes GetPixel and SetPixel functions to allow end user modification of bitmap data.
• Fully supports the UNICODE programming model.

Internally the class makes use of the Microsoft DIBAPI code which is supplied with CDibImage in an unmodified form. The Microsoft code is very C/SDK based and does not sit very well with the object oriented C++ paradigm, hence one of the reasons I developed CDibImage. I am also very interested in image processing and wanted to implement something concrete to use in my own test programs. I also wanted something which was reusable and extensible so that I could easily allow new filters and working areas to be added without modifying the base code. All the image processing, clipboard and undo/redo support is original code developed by the author. Currently only DIB (aka Windows Bitmap files) are supported by CDibImage but it would not be much work to extend it to support other image file formats.

HISTORY:

V1.0 (18 November 1997)

• Initial public release.

INSTALLATION:

The classes are for Win32 only and have been tested with the following compilers: VC 4.1, 4.2 & VC 5. To help keep the download size to a minimum, there is no install program. All you need to do is unzip the "dibimage.zip" file into a directory on your hard disk. Please note that the zip file uses long filenames so you will need to run an unzip program which preserves long filenames such as WinZip. From there you can view the CDibImage documentation (this file), or load up the demo application "DibEdit". This program uses the CDibImage classes to demonstrate most of the features of CDibImage. Please note that the binary version of DibEdit included in the zip file was build with VC 4.2b so you will need the obligatory MFC dll's installed to run it. If you want to recompile it with your copy of Visual C++, then just load up the "dibedit.mak" file into Developer Studio and do a "Rebuild All".

CLASSES PROVIDED:

CWorkingArea

This class encapsulates a working area. This is the area which any operation on a dibimage will only affect. The class is pure virtual and has been implemented in such a way that the user of CDibImage can implement a new class derived from it which CDibImage can use straight away. Examples could include a CCircleWorkingArea or CPolygonWorkingArea.

virtual BOOL CWorkingArea::PointInSelection(const CPoint& point)=0;

This pure virtual function should return TRUE if the point is inside the working area otherwise FALSE.

virtual CRect CWorkingArea::BoundingRectangle();

This pure virtual function should return the bounding rectangle for the working area. This is used by CDibImage to help improve performance when a image processing effect is being performed.

virtual CWorkingArea* CWorkingArea::Clone();

This pure virtual function should return a pointer to a newly allocated copy of this working area. This is used by CDibImage when copying a DIB to a new variable.

CRectWorkingArea

CRectWorkingArea::CRectWorkingArea(CRect rect);

Constructs a rectangular working area given a CRect.

virtual BOOL CRectWorkingArea::PointInSelection(const CPoint& point);

Override of the pure virtual function of the parent class. In the case of a simple rectangular selection, it returns TRUE if the point "point" is inside the rectangle.

virtual CRect CRectWorkingArea::BoundingRectangle();

Override of the pure virtual function of the parent class. In the case of a simple rectangular selection, it returns TRUE if the point "point" is inside the rectangle.

virtual CWorkingArea* CRectWorkingArea::Clone();

Returns a newly allocated copy of this class.

CUserDefinedFilter

This is the base class from which all filter objects should be derived. The base class defines one pure virtual method which must be overridden in derived classes to provide a concrete class.

virtual COLORREF CUserDefinedFilter::Filter(CDibImage& dibImage, LPSTR lpDibBits, int x, int y)=0;

Virtual function which takes a dib image, a pointer to its data bits and a position to filter. The return value is the filtered result.

C3By3Filter : public CUserDefinedFilter

This class implements a simple 3*3 convolution kernel filter. The class includes 3 public member variables which represent the filter values. They are:

int m_nValues[3][3]: The actual filter values
int m_nDivision: A scaling value which is applied after the convolution
int m_nBias: A bias value to add after the convolution

C3By3Filter::C3By3Filter();

Standard Constructor

virtual COLORREF C3By3Filter::Filter(CDibImage& dibImage, LPSTR lpDibBits, int x, int y);

Reimplementaion of the virtual function which takes a dib image, a pointer to its data bits and a position to filter. The return value is the filtered result.

C5By5Filter : public CUserDefinedFilter

This class implements a simple 5*5 convolution kernel filter. The class includes 3 public member variables which represent the filter values. They are:

int m_nValues[5][5]: The actual filter values
int m_nDivision: A scaling value which is applied after the convolution
int m_nBias: A bias value to add after the convolution

C5By5Filter::C5By5Filter();

Standard Constructor

virtual COLORREF C5By5Filter::Filter(CDibImage& dibImage, LPSTR lpDibBits, int x, int y);

Reimplementation of the virtual function which takes a dib image, a pointer to its data bits and a position to filter. The return value is the filtered result.

C3By3MedianFilter : public CUserDefinedFilter

This class implements a simple 3*3 median filter.

C3By3MedianFilter::C3By3MedianFilter();

Standard Constructor.

virtual COLORREF C3By3MedianFilter::Filter(CDibImage& dibImage, LPSTR lpDibBits, int x, int y);

Reimplementation of the virtual function which takes a dib image, a pointer to its data bits and a position to filter. The return value is the filtered result.

C7By7Filter : public CUserDefinedFilter

This class implements a simple 7*7 convolution kernel filter. The class includes 3 public member variables which represent the filter values. They are:

int m_nValues[7][7]: The actual filter values
int m_nDivision: A scaling value which is applied after the convolution
int m_nBias: A bias value to add after the convolution

C7By7Filter::C7By7Filter();

Standard constructor

virtual COLORREF C7By7Filter::Filter(CDibImage& dibImage, LPSTR lpDibBits, int x, int y);

Reimplementation of the virtual function which takes a dib image, a pointer to its data bits and a position to filter. The return value is the filtered result.

CDibImage

This is the main class which provides an MFC C++ class interface to Device Independent Bitmaps.

CDibImage::CDibImage();

Standard Constructor

CDibImage::~CDibImage();

Standard destructor

BOOL CDibImage::Attach(HGLOBAL hGlobal);

This function attaches to a piece of global memory which contains a DIB inside it. This is used internally by the routines which load from file. It is also used by the clipboard functions in CDibImage.

void CDibImage::Destroy();

This is the complement of CDibImage::Attach and releases the memory associated with it. It is called as part of the cleanup sequence in CDibImage::~CDibImage()

BOOL CDibImage::Create(CSize size, WORD nBitCount);

This creates a new dib given a size and a bitcount (1 mono, 4, 16 colors, 8 256 colors, 15 32k colors, 16 64k colors and 24 16 million colors). Please bear in mind that currently the CDibImage class requires all DIBs to be in 24 bit colour to support any of the image processing functions.

static WORD CDibImage::GetVersion();

This returns the version number of the CDibImage project. It currently returns 1.0 encoded as 0x0100.

static void CDibImage::RGBtoHSL(COLORREF rgb, double* H, double* S, double* L);

This static function performs conversion from the RGB (Red Green Blue) to HSL (Hue Saturation Luminance) colour space. Values are returned in the H, S & L parameters. Please bear in min the HSL components are represented by real numbers whereas the input value rgb uses a Windows integer representation of the RGB colour space.

static COLORREF CDibImage::HLStoRGB(const double& H, const double& L, const double& S);

This static function performs conversion from the HSL (Hue Saturation Luminance) to RGB (Red Green Blue) colour space.

BOOL CDibImage::Load(LPCTSTR lpszPathName);

This function loads a DIB from file given a filename "lpszPathName". Internally the CDibImage::Attach function is used to attach to the memory image of the DIB.

BOOL CDibImage::Load(HINSTANCE hInst, LPCTSTR lpResourceName);

This function loads a DIB from a resource. Unlike CBitmap::LoadBitmap, the palette information is preserved. Hinst is the instance handle to load from and lpResourceName is the name of the resource to load.

BOOL CDibImage::Load(HINSTANCE hInst, UINT uID);

This function loads a DIB from a resource. Unlike CBitmap::LoadBitmap, the palette information is preserved. Hinst is the instance handle to load from and uID is the resource ID of the resource to load.

BOOL CDibImage::Save(LPCTSTR lpszPathName);

This function saves a DIB to disk file.

BOOL CDibImage::CopyToClipboard();

Copies the current working area of this DIB onto the clipboard.

BOOL CDibImage::PasteFromClipboard();

Pastes the DIB on the clipboard into the DIB. Please note that it will completely replace the current dib.

static BOOL CDibImage::PasteAvailable();

Static function which returns TRUE if a DIB is available on the clipboard for pasting.

CDibImage::CDibImage(const CDibImage& ds);

Standard C++ copy constructor which makes this instance a copy of the "ds" DIB.

CDibImage& CDibImage::operator=(const CDibImage& ds);

Standard C++ operator= which makes this instance a copy of the "ds" DIB.

BOOL CDibImage::CopySelection(CDibImage& dib);

Copies the working area of DIB "dib" into this DIB. Please note that it will completely replace the current dib.

void CDibImage::SetUndoSize(int nUndoSize);

Sets the size of the undo stack to associate with this DIB. Please note that the bigger the undo size, the more memory that will be required. This is important as large DIBs could consume a lot of memory. If you are performing an image processing function and you are not worried about about undo capabilities then set the undo size to 0. This will improve performance as well as reduce memory requirements for your program.

int CDibImage::UndoSize() const;

Returns the current undo size for this DIB.

BOOL CDibImage::SaveState(const CString& sDescription);

Pushes the current state of the DIB onto the the Undo stack. This is performed internally before any operation which can modify the state of the DIB. The sDescription string can be used to associate a name with the operation which is about to take place. This is useful for implement customised text on an edit menu which supports Undo. See the DibEdit sample for an example of this.

BOOL CDibImage::SaveState(UINT nID);

Pushes the current state of the DIB onto the the Undo stack. This is performed internally before any operation which can modify the state of the DIB. The nID is the string resource ID of a string can be used to associate a name with the operation which is about to take place. This is useful for implement customised text on an edit menu which supports Undo. See the DibEdit sample for an example of this.

BOOL CDibImage::UndoAvailable();

Returns TRUE if there is currently something is on the undo stack for this DIB.

BOOL CDibImage::Undo();

Performs a undo by pushing the current image onto the redo stack and popping the top image from the undo stack into the current image.

BOOL CDibImage::Redo();

Performs a redo by pushing the current image onto the undo stack and popping the top image from the redo stack into the current image.

BOOL CDibImage::RedoAvailable();

Returns TRUE if there is currently something is on the redo stack for this DIB.

CString CDibImage::UndoDescription() const;

Returns a string describing what the next undo will perform.

CString CDibImage::RedoDescription() const;

Returns a string describing what the next redo will perform.

CWorkingArea* CDibImage::GetWorkingArea();

Returns a pointer to the working area currently associated with this DIB.

void CDibImage::SetWorkingArea(CWorkingArea* pWorkingArea);

Sets the working area currently associated with this DIB. The working area is the area outside of which processing functions will not affect this DIB.

int CDibImage::ColorsUsed() const;

Counts the number of unique colors in this DIB. (Currently not implemented)

LPSTR CDibImage::GetDIBBits()

This returns a pointer to the actual DIB data.

BOOL CDibImage::SetColor(COLORREF color);

Sets the colour of all the pixels inside the working area to "color".

BOOL CDibImage::Flip();

Flips the pixels inside the working area for this DIB vertically.

BOOL CDibImage::Mirror();

Flips the pixels inside the working area for this DIB horizontally.

BOOL CDibImage::AdjustBrightness(int Percentage);

Adjusts the brightness of the pixels inside the working area by a certain amount. 100 means no change, less than 100 will make the image darker and greater than 100 will make the image brighter.

BOOL CDibImage::AdjustContrast(int Percentage);

Adjusts the contrast of the pixels inside the working area by a certain amount. 100 means no change, less than 100 will decrease the contrast and greater than 100 will increase the contrast of the image. This corresponds to stretching the histogram of the image horizontally about the centre point of 127.

BOOL CDibImage::AdjustGammaCorrection(float Value);

Changes the gamma correction of the image to "Value".

BOOL CDibImage::AdjustHighLight(int Percentage);

This increases the brightness of the light areas (> 170 value) by a certain percentage. This corresponds to increasing the height of the last 1/3 of the histogram.

BOOL CDibImage::AdjustMidtone(int Percentage);

This increases the brightness of the midtone areas (>= 85 & <= 170 value) by a certain percentage. This corresponds to increasing the height of the middle 1/3 of the histogram.

BOOL CDibImage::AdjustShadow(int Percentage);

This increases the brightness of the dark areas (< 85 value) by a certain percentage. This corresponds to increasing the height of the first 1/3 of the histogram.

BOOL CDibImage::AdjustHue(int Percentage);

This increases the hue of the working area by a certain percentage. 100 means no change, less than 100 decreases the hue content and greater than 100 will increase the image brighter.

BOOL CDibImage::AdjustSaturation(int Percentage);

This increases the colour saturation of the working area by a certain percentage. 100 means no change, less than 100 decreases the saturation content and greater than 100 will increase the saturation content.

BOOL CDibImage::AdjustHSL(int PercentHue, int PercentSaturation, int PercentLuminosity);

This increases the hue, saturation and luminosity of the working area in one function call. This function is provided in addition to the functions to individually changes the values as the 3 values are calculated for each individucal function, hence modifying the values at once is much quicker.

BOOL CDibImage::AdjustRed(int Percentage);

This increases the red content of the working area by a certain percentage. 100 means no change, less than 100 decreases the red content and greater than 100 will increase the content.

BOOL CDibImage::AdjustGreen(int Percentage);

This increases the green content of the working area by a certain percentage. 100 means no change, less than 100 decreases the green content and greater than 100 will increase the content.

BOOL CDibImage::AdjustBlue(int Percentage);

This increases the blue content of the working area by a certain percentage. 100 means no change, less than 100 decreases the green content and greater than 100 will increase the content.

BOOL CDibImage::Greyscale();

This converts the contents of the working area to a greyscale.

BOOL CDibImage::Negate();

This negates the contents of the working area.

BOOL CDibImage::FindEdgesFilter();

Applying this filter to a dib will emphasise the edges found in the working area.

BOOL CDibImage::FindVerticalEdgesFilter();

Applying this filter to a dib will emphasise the vertical edges found in the working area.

BOOL CDibImage::FindHorizontalEdgesFilter();

Applying this filter to a dib will emphasise the horizontal edges found in the working area.

BOOL CDibImage::BlurFilter();

Applying this filter to a dib will blur the working area.

BOOL CDibImage::AddNoiseFilter(int Percentage);

Applying this filter to a dib will add a uniform noise to the working area. The Percentage will determine the coverage of the noise. A value of 1 will mean every 100 pixel on average will have up to color value modified by up to 128.

BOOL CDibImage::MedianFilter();

Applying this filter to a dib will perform a median filter on the working area.

BOOL CDibImage::UserDefinedFilter(CUserDefinedFilter& Filter);

This function allows any user-defined filter to be applied to this DIB. You can develop you own filters by deriving from CUserDefinedFilter and implementing the pure virtual function Filter().

BOOL CDibImage::SplitChannels(CDibImage& red, CDibImage& green, CDibImage& blue);

This function will separate the contents of this DIB into 3 new DIBs which represent the 3 constituent RGB channels. The three channels are returned in the variables "red", "green" & "blue"

BOOL CDibImage::CombineChannels(const CDibImage& red, const CDibImage& green, const CDibImage& blue);

This function is the corollary of the function SplitChannels and will combine 3 DIBs into this DIB which represents the 3 input channels.

BOOL CDibImage::GetRedChannel(CDibImage& red);

This function will extract the red channel from this DIB and put the result into the variable "red".

BOOL CDibImage::GetGreenChannel(CDibImage& green);

This function will extract the green channel from this DIB and put the result into variable "green".

BOOL CDibImage::GetBlueChannel(CDibImage& blue);

This function will extract the blue channel from this DIB and put the result into variable "blue".

BOOL CDibImage::Draw(CDC& dc, const CRect* rcDst=NULL, const CRect* rcSrc=NULL, CPalette* pPal=NULL);

This function will draw this DIB unto the device context "dc". The destination rectangle and source rectangles are rcDst amd rcSrc respectively. Leaving these values NULL will use the image rectangle as a default. The palette to use is represented by pPal. Again leaving this NULL, will use the palette associated with this DIB.

CSize CDibImage::Size() const;

Returns the size of this DIB as a CSize variable.

CRect CDibImage::Rect() const;

Returns the size of this DIB as a CRect variable.

int CDibImage::Width() const;

Returns the width of this DIB as an integer.

int CDibImage::Height() const;

Returns the height of this DIB as an integer.

int CDibImage::ScanWidth() const;

Returns the scan line width associated with this DIB in bytes. This values is dependent on the color depth of this DIB and the DWORD alignment which is used for DIBs.

int CDibImage::BitsPerPixel() const;

This returns the number of bits used for each pixel. Possible values are 1 (Mono), 4 (16 Colors), 8 (256 Colors), 16 (56K Color), 24 (16M Color) or 32 (16M Color + transparency).

BOOL CDibImage::GetPixel(int x, int y, COLORREF& value, LPSTR lpDibBits = NULL) const;

This returns the pixel colour at a certain position at offset (x,y) in this DIB. The value is returned in "value". The lpDibBits value is a pointer to the pixel data. Normally inside double loops for area image effects this should be calculated once outside of the loop by calling GetDIBBits().

BOOL CDibImage::SetPixel(int x, int y, const COLORREF& value, LPSTR lpDibBits = NULL);

This sets the pixel colour at a certain position at offset (x,y) in this DIB. The lpDibBits value is a pointer to the pixel data. Normally inside double loops for area image effects this should be calculated once outside of the loop by calling GetDIBBits().

BOOL CDibImage::GetRedHistogram(int* RedChannel, int nSize);

This returns an array of values in "RedChannel" up to size "nSize" with a count in each which represents how many pixels in the working area had a red value equal to the offset into RedChannel.

BOOL CDibImage::GetGreenHistogram(int* GreenChannel, int nSize);

This returns an array of values in "GreenRedChannel" up to size "nSize" with a count in each which represents how many pixels in the working area had a green value equal to the offset into GreenChannel.

BOOL CDibImage::GetBlueHistogram(int* BlueChannel, int nSize);

This returns an array of values in "BlueChannel" up to size "nSize" with a count in each which represents how many pixels in the working area had a blue value equal to the offset into BlueChannel.

BOOL CDibImage::GetHistogram(int* RedChannel, int nRedSize, int* GreenChannel, int nGreenSize, int* BlueChannel, int nBlueSize);

This returns 3 arrays which contain the histogram information for each of the 3 channels. This allows you to more quickly perform what GetRedHistogram, GetGreenHistogram and GetBlueHistogram allow you to do individually.

PLANNED ENHANCEMENTS:

• See the top of dibimage.cpp for a list of functions which are being considered for inclusion in the next version of CDibImage.The "DibEdit" sample contains a number of disabled menu items which match the functions which are currently not implemented.
• If you have any other suggested additions, comments or bug fixes, please let me know so that I can try my best to incorporate them into the next version of CDibImage.

SHAREWARE NOTICE:

CDibImage is shareware and this trial version is a fully functional evaluation copy. This means that you are free to evaluate CDibImage for up to 30 days. After this period if you are still using the CDibImage classes and/or wish to include it in a project of yours, then you are legally obliged to register CDibImage with the author. Registration will entitle you to comprehensive email support from the author. The cost is $30 US dollars. Payment should be made by cheque and be made out to:

CONTACTING THE AUTHOR

PJ Naughter
Email: pjn@indigo.ie
Web: http://indigo.ie/~pjn
18th November 1997