This documentation is for the old version. Go to the latest Graphics Mill docs

Displaying Image in BitmapViewer Windows Control

To display the image in the form of your application Graphics Mill for .NET provides a special control called BitmapViewer. This article gives guidelines how to use this control.

Associate the Image with the BitmapViewer

To associate the image with the BitmapViewer, you should use the Bitmap property. You can use the Load method to load the image from the file:

Visual Basic

Alternatively, you can assign existing instance of the Bitmap class to this property. However in this case it is highly recommended to dispose of the image which is currently associated with the BitmapViewer. Otherwise the reference to this image will become orphan, and this image will occupy memory until the garbage collector removes it completely. If the image is quite large, and the Bitmap property is updated too often, the application may suddently run out of memory.

To avoid this effect, we recommend to update the Bitmap property with a similar code:

Visual Basic
Dim oldBitmap As Aurigma.GraphicsMill.Bitmap = BitmapViewer1.Bitmap
BitmapViewer1.Bitmap = newBitmap
Aurigma.GraphicsMill.Bitmap oldBitmap = BitmapViewer1.Bitmap;
BitmapViewer1.Bitmap = newBitmap;

After the image stored in the Bitmap property is modified, the control raises the WorkspaceChanged event. Also, if the AutoUpdate property is set to true, the bitmap is redrawn in the control. If you are making several modifications to the image (e.g. drawing a graphics which consists of several elements), you may prefer to disable this automatic update and refresh the control manually with the Invalidate method. It will increase the performance.

Zooming the Image in the BitmapViewer

BitmapViewer allows zooming in two modes: manual and automatic.

Manual Zoom

Manual zooming may be done by modifying the Zoom property. When this property equals 1, no zooming is done (i.e. the image is displayed in its actual size). When the property is less than 1, the image is shrunk (e.g. 0.5 means 50% of the actual size), when it is greater than 1, it is stretched (e.g. 3 means 300% of the actual size).

Zooming may be also done via mouse events. When the user holds the Shift button and scrolls the mouse wheel, the image is zoomed. The amount of zoom done with this method depends on the WheelZoomAmount property value.

Alternatively, you can associate some zooming navigator control, which will zoom the image on the mouse click. You can get more information about it in the topic Using Navigators and Rubberbands (Window Forms).

Image may be zoomed with a different quality. If it is zoomed with low quality, the performance is higher, and vice versa. Also, often low quality is preferable for stretching the image (so that the pixelization effect is visible) since it gives more control when drawing or selecting something. The quality of the zooming is specified with the ZoomQuality property.

Maximum and minimum zoom values can be limited. Use MinZoom and MaxZoom to specify maximum and minimum zoom value correspondingly.

If you need to perform some specific actions when the image is zoomed (e.g. display the zoom factor somewhere), you should handle the Zoomed event.

Automatic Zoom

Automatic zooming is used when you need to the image to completely fit the control (i.e. occupy maximum area of the control without displaying the scroll bars). It can also be set to maintain such zoom ratio to fit the image in the control by width, etc.

To make the control get the zoom ratio automatically, use the ZoomMode property. It can be one of the following modes:

  • None. Manual mode is used.
  • Best fit. The image is shrunk or stretched to fill maximum area of the control without displaying the scroll bars.
  • Best fit shrink only. The same, but if the image dimensions are less than the contol size, no zooming is applied.
  • Fit to width. The image is shrunk or stretched to fit the control horizontally.
  • Fit to width shrink only. The same, but if the image width is less than the contol width, no zooming is applied.
  • Fit to height. The image is shrunk or stretched to fit the control vertically.
  • Fit to height shrink only. The same, but if the image height is less than the contol height, no zooming is applied.
  • Control to image size. This mode is the only one, which updates the control dimensions instead of zooming the image . With this mode the control client area size is updated to be the same as the image dimensions.

Pay attention, when you use zooming navigators, the ZoomMode is automatically reset to None.

Image Rendering

You may also manage image rendering parameters.

Alpha Blending

If you are displaying an image which contains some transparent or semi-transparent areas, the BitmapViewer can maintain these areas by alpha blending them with the background. However, it works noticeably slower than plain pixel copying. So if there is no need to maintain the transparent areas of images, you can disable it using the AlphaEnabled property.

If you enable alpha blending, you may wonder how to specify the background settings. The BitmapViewer allows to specify the style and colors of the background.

The background style is specified with the WorkspaceBackgroundStyle property and can be one of the following styles:

  • None. No specific background for the image is used. The background color is the same as a background color of the entire control.
  • Solid. The background of the bitmap is filled by the solid color which is specified by the WorkspaceBackColor1 property.
  • Grid. The background of the bitmap is a "checkerboard", i.e. it consists of alternating squares of two colors which are set with the WorkspaceBackColor1 and WorkspaceBackColor2 properties. It is helpful when you need to demonstrate what portions of the image are transparent.

Color Management

If you need accurate displaying of the colors, you can enable color management for the BitmapViewer. It is done using the ColorManagementEngine property.


Since the displaying with the color management is quite slow, if accuracy of the colors is not important, it is recommended to set this property to false to increase the performance.

The ColorManagementEngine property overrides the color management settings of the Bitmap associated with the BitmapViewer. However if the Bitmap has no input profile (i.e. its ColorProfile property is not initialized with some profile), color management cannot be applied.


You don't need to specify the output profile yourself. Graphics Mill for .NET automatically determines the profile of your monitor and uses it.

Maintaining the Physical Size of the Image

When you are creating an image which should be printed, you may need to see this image in its physical size. For example, if the image is 900 pixels wide and 1500 pixels high, and you are going to print it with 300 DPI resolution, the physical size will be 3x5 inches. To make BitmapViewer convert pixels to inches, set the ScaleToActualSize property to true.

It will also provide proper displaying of the images which have different horizontal and vertical resolutions. Different resolutions are typical for such images as faxes. If you disable the ScaleToActualSize mode, such faxes will look flattened out.

However since enabling the ScaleToActualSize mode leads to additional zooming, it works slower. So if you do not need to preserve the physical size of the image, it is recommended to set this property to false to increase the performance.