Image Viewer Items

ImageViewer supports one or more items with each containing its own image data, size and optional additional transformation.

Using Items

To access the items, use the ImageViewer.Items property. This is of type ImageViewerItems which implements standard ICollection and IList interfaces to easily add/remove/get/set and enumerate the items:

Member

Description

ImageViewerItems.Add

Adds a new item to the viewer

ImageViewerItems.Insert

Inserts at the specified index a new item to the viewer

ImageViewerItems.Remove

Removes an item from the viewer

ImageViewerItems.RemoveAt

Removes the item at the specified index from the viewer

ImageViewerItems.Clear

Delete all the items from the viewer

ImageViewerItems.Item

Gets or sets an item at the specified index

ImageViewerItems.Contains

Determines whether an item is in the viewer

ImageViewerItems.IndexOf

Gets the index of the specified item

When an items list or the properties of an item has changed, the following event occur in the image viewer:

Or by letting the viewer load it (using the internal RasterCodecs instance) by setting the URL:

// Create an itemImageViewerItem item = new ImageViewerItem(); // Load an image into ititem.Url = new Uri(@"C:\Users\Public\Documents\LEADTOOLS Images\Ocr1.tif"); // Add it to the viewerimageViewer.Items.Add(item);

// Add an item directly from a URLimageViewer.Items.AddFromImageUrl(new Uri(@"C:\Users\Public\Documents\LEADTOOLS Images\Ocr1.tif"));

In the cases above, you can easily obtain the item added for further modification by using the return value from the methods or accessing the ImageViewer.Items collection.

ImageViewer also supports adding SVG items. They can be SVG files or any document format that supports loading as SVG. This code will load a page from a PDF file as SVG and add an item for it:

// Create an itemImageViewerItem item = new ImageViewerItem(); // Load a page from a PDF file as SVG and set it in the itemusing (RasterCodecs codecs = new RasterCodecs()) item.SvgDocument = codecs.LoadSvg(@"C:\Users\Public\Documents\LEADTOOLS Images\Leadtools.pdf", 1, null) as SvgDocument; // Add it to the viewerimageViewer.Items.Add(item);

Similarly to using RasterImage, you can let the viewer load the SVG document by setting the URL. An extra step is required:

// Create an itemImageViewerItem item = new ImageViewerItem(); // Tell the item to load the data in the URL as SVG, not a RasterImageitem.LoadUrlAsSvg = true; // Load an image into ititem.Url = new Uri(@"C:\Users\Public\Documents\LEADTOOLS Images\Leadtools.pdf"); // Add it to the viewerimageViewer.Items.Add(item);

// Add an item directlyusing (RasterCodecs codecs = new RasterCodecs()) { for (int i = 1; i <= 4; i++) { string fileName = string.Format(@"C:\Users\Public\Documents\LEADTOOLS Images\Ocr{0}.tif", i); RasterImage rasterImage = codecs.Load(fileName, 1); imageViewer.Items.AddFromImage(rasterImage, 1); } } // pan and zoom to see all the images on top of each other

It is always recommended to disable the viewer from updating while multiple items are added (or removed, or updated). Doing so will ensure that the viewer does not waste resources updating its transformations and re-painting while it is in an intermediate state:

With multiple items, it is sometimes desired to add items at a certain location. This can easily be accomplished using ImageViewerItems.Insert which accepts as a parameter the index of the new item. All the direct add methods (such as AddFromImage) also have an insert counterpart (Such as InsertFromImage)

Removing items from the viewer is performed as follows. Start from the example code above and add the following:

// Remove the first itemimageViewer.Items.RemoveAt(0);

Run the demo again, note that the viewer is displaying three items instead of four starting from page 2. ImageViewerItems.Remove can be used to remove an item by its reference. ImageViewerItems.Clear will remove all the items from the viewer (and sets the ActiveItem property to null)

Relationship between Item and Image Size

Each ImageViewerItem has two properties to determine the size of the item and its image:

ImageViewerItem.ImageSize stays empty. This item will be invisible and will not participate in the layout calculation. The size can be set at a later time if desired to make the item visible.

Not empty

Available

The viewer will not calculate the value from the image data, instead, the value is used as is. The viewer will automatically stretch or shrink the image data when calculating the transformation or rendering to match the size.

Not empty

Not Available

The viewer will treat the item as it has image data with the specified size. It will use this value in the transformation calculation but will not render any image data. The ImageViewerVirtualizer uses this mode extensively to render a place holder of the actual image till the data is available. This mode can also be used to custom render image data.

Item Size

This is the default mode. The viewer will use the value of ImageViewer.ItemSize calculated above and set it in ImageViewerItem.Size. Hence, the item will have the same value for both and the image will occupy the full item area

The viewer will set the value of ImageViewer.ItemSize into ImageViewerItem.Size. All the items will have the same size and each image will be placed and rendered inside the item depending on their own ImageViewerItem.ImageSize values and alignment. This mode is useful when the viewer is used as an "image list" or "thumbnails browser".

Usually you set ImageViewer.ItemSize to a specified value when the viewer is used as an "image list" or "thumbnails browser". To accomplish this, set the value of ItemSize to the desired thumbnail size plus padding. For example, 200 by 200 pixels. Then add the items with their own ImageViewerItem.Size set to the default value of LeadSize.Empty. As described above, the viewer will update ImageViewerItem.Size to be equal to 200 by 200 pixels as well. One more thing to consider in this mode is how the image inside each item is displayed. In image list mode, it's probably desired to fit each image inside this size (200 by 200 pixels in the case above), so set the value of ImageViewer.ItemSizeMode to Fit or FitAlways.

Resolution

ImageViewerItem also has the Resolution property. This must be set to the resolution (in dots per inch) of the original image data if accounting for the logical size of the image when displayed is desired.

For example, a typical A4 document image is 8.5 by 11 inches. Which could be 2550 by 3300 pixels if the image has a resolution of 300 by 300. Most document viewer applications will try to display this image in its original size. In other words, the image will take 8.5 inches of screen horizontal space and 11 inches of screen vertical space. If you do not use the ImageViewer.UseDpi property for this control, you are required to do the calculations yourself as follows:

In the case of the image above, this will be 96 (typical screen resolution) divided by 300. Or, you can set the ImageViewer.UseDpi value to true and the control will use the above formula internally keeping the ScaleFactor set to 1 as follows:

viewer.UseDpi = true; viewer.Zoom(1);

This code will produce the same results as the first code snippet.

In platforms where the screen resolution can be obtained programmatically (such as Windows.Forms), the value of ImageViewer.ScreenDpi is set automatically by the image viewer upon creation.

In platforms where the screen resolution cannot be obtained programmatically (such as JavaScript), the value of ImageViewer.ScreenDpi is set to the default value of 96.

When adding a new item to the viewer, the value of ImageViewerItem.Resolution will be checked. If the value is empty (or 0,0), then the viewer will try to obtain this value from this image data in platforms where this information can be obtained programmatically (such as Windows.Forms).

In platforms where the resolution cannot be obtained automatically (such as JavaScript), then it's the user responsibility to set the value. For example, the LEADTOOLS HTML 5 Viewer Demo uses the LEADTOOLS REST services to obtain this value and set it for the item.

In either case, the user can then manually modify this value is desired.

Image Ownership

RasterImage and SvgDocument are both IDisposable objects. Eventually, some part of the code need to dispose these objects when they are no longer needed. This is controlled by using the ImageViewer.AutoDisposeImages property. In the examples above, we left the value of this property to the default of true. Hence, the viewer disposes the image or SVG document when the item is removed. To prevent that, set the value of AutoDisposeImages to false.

Active Item

ImageViewer will always have an item denoted as the "Active", this can be accessed through the ImageViewer.ActiveItem property. This property cannot be set to null unless there are no more items in the viewer.

When an item is removed, the viewer will automatically check if it was the active item and if so, will set the next closest item as the new active.

The ActiveItem is important when using the viewer in a single item mode as described below.

Single Item Mode

Some application such as the Main Demo shipped with LEADTOOLS does not require multiple items in the image viewer and will always have a single item that either has image data or not.

For these type of application, the image viewer provides shortcuts for all the properties and method that would normally require accessing the ImageViewer.Items collection or modifying ImageViewerItem.

To achieve this, the image viewer layout must be set to ImageViewerSingleViewLayout and an empty item must be set in ImageViewer.Items. This item will be the ActiveItem since the image viewer must have an active item at all times. This is precisely what happens when you create a new instance of ImageViewer using the default constructor, code:

// Create a new image viewer instance using the default constructorImageViewer imageViewer = new ImageViewer(); // Set some propertiesimageViewer.Dock = DockStyle.Fill; // Add it to the formthis.Controls.Add(imageViewer); // Verify that we have a view layout, and it is of type singleDebug.Assert(imageViewer.ViewLayout != null && imageViewer.ViewLayout is ImageViewerSingleViewLayout); // Verify that we have a single itemDebug.Assert(imageViewer.Items.Count == 1); // Verify that we have an active itemDebug.Assert(imageViewer.ActiveItem != null); // Load an image into itusing (RasterCodecs codecs = new RasterCodecs()) imageViewer.Image = codecs.Load(@"C:\Users\Public\Documents\LEADTOOLS Images\Ocr1.tif", 1); // Show the image sizeMessageBox.Show("ImageSize: " + imageViewer.ImageSize.ToString());