Displaying Image in BitmapViewer (Web Controls)

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:

BitmapViewer1.Bitmap.Load(OpenFileDialog1.FileName)

bitmapViewer1.Bitmap.Load(openFileDialog1.FileName);

Alternatively, you can assign an 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 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:

Dim oldBitmap As Aurigma.GraphicsMill.Bitmap = BitmapViewer1.Bitmap
BitmapViewer1.Bitmap = newBitmap
oldBitmap.Dispose()

Aurigma.GraphicsMill.Bitmap oldBitmap = BitmapViewer1.Bitmap;
BitmapViewer1.Bitmap = newBitmap;
oldBitmap.Dispose();

After the image stored in the Bitmap property is modified, the control sends the updated image to the client.

Pay attention, the control sends to the client only that portion of the image which is actually visible in the viewport. Moreover, if some part of the image has already been delivered to the client, it is not resent. In brief, the scheme of displaying an image is the following:

1. If the preview image is enabled (i.e. PreviewImageEnabled property is set to true), the BitmapViewer prepares this image (the size depends on the PreviewImageResizeRatio property), saves it in the public cache, and sends it to the client.
2. The preview is stretched across the entire control area (including invisible parts). The preview looks extremely pixelated, but still allows user to navigate the control.
3. The control calculates the portion of the image to download:
   • If nothing is loaded into the viewport, it requests a portion of the image of the same size and coordinates as the viewport (taking zoom into account).
   • If the viewport contains a part of the image, it calculates coordinates of rectangles which cover the rest image displayed in the viewport. Currently it tries to cover the unloaded part of the image with two rectangles. If it cannot be done, the entire viewport is reloaded.
   • If the image was entirely loaded into the viewport, no re-downloading occurs. This way if the user scrolls to the portion of image which has been already loaded, they don't need to download it again.
4. At server side the required portions of the image are cropped and zoomed, and then sent to the client.
5. These portions of image are laid over the preview image.

Zooming the Image in the BitmapViewer

BitmapViewer allows zooming in two modes: manual and automatic. To maintain zooming, you can use both server and client properties of the BitmapViewer.

Manual Zoom

Manual zooming may be done by modifying the Zoom server property or using JavaScript method getZoom/setZoom. 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).

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 (Web 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 server properties to specify maximum and minimum zoom value correspondingly. You can read these values in the JavaScript using getMinZoom and getMaxZoom methods.

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 server event. To be able to handle this event at the client side, use addZoomed/removeZoomed JavaScript methods.

Automatic Zoom

Automatic zooming is used when you need the image to completely fit the control (i.e. occupy maximum area of the control without displaying the scroll bars). It can 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 server property or the getZoomMode/setZoomMode JavaScript methods. 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 scroll bars.
• Best fit shrink only. The same, but if the image dimensions are less than the control 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 control 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 control 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.