Exploring the MultiScaleImage API
,Before diving into the sample code for this section, let’s look at some of the key features of the MultiScaleImage API.
Instantiating a MultiScaleImage can be done in XAML, as shown:
<MultiScaleImage Source="http://www.example.com/dzc_output.xml" />
Or in code:
MultiScaleImage multiScaleImage = new MultiScaleImage();
multiScaleImage.Source = new DeepZoomImageTileSource(
new Uri("http://www.example.com/dzc_output.xml"));
Source Property
When set in XAML, the Source property of the MultiScaleImage indicates the URL of the Deep Zoom image definition file, an XML file containing image metadata, and paths to subimage definition files. The Source property type is, however, an abstract class called MultiScaleTileSource, with an abstract method GetTileLayers. This offers an extensibility point for generating dynamic Deep Zoom images, although that is beyond the scope of this book.
Logical and Element Coordinates
As you see, some properties and methods of the MultiScaleImage rely on logical coordinates rather than element coordinates. Logical coordinates (also known as normalized coordinates) are points whose X and Y axis values are between 0 and 1. The methods ElementToLogicalPoint and LogicalToElementPoint are used to convert to and from both coordinate types. For example, calling ElementToLogicalPoint with a touch Point at the center of the control, returns a Point with X and Y coordinates of 0.5. Conversely, calling LogicalToElementPoint, with a Point(0.5, 0.5) and where the control measures 200 by 200 pixels, returns a Point with X and Y coordinates of 100.
SubImages Property
The SubImages property provides access to a collection of MultiScaleSubImage objects, which is populated if the Deep Zoom image is composed of multiple images, rather than a single high-resolution image. This is useful if you want to programmatically move individual images around the screen, or filter your images.
ViewportOrigin and ViewportWidth Properties
The ViewportOrigin and ViewportWidth properties are both Point objects that use logical coordinates. They work in conjunction to determine the zoom level of the image and the visible area of the image. The ViewportOrigin specifies the position of the image and is the location of the top-left corner of the image, whereas the ViewportWidth is how wide the viewport window is relative to the entire image. In other words, ViewportWidth is the fraction of the width of the image that is visible. The following is a list of ViewportWidth values and their effects:
ViewportWidth = 1—When equal to one, the entire image is displayed. This is the default value.
ViewportWidth < 1—When less than 1, the image is zoomed in. The closer you get to zero, the more zoomed in the image appears. Zero is completely zoomed in and the user cannot see the image at all.
ViewportWidth > 1—When greater than 1, the image is zoomed out, and the value indicates the number of times that the viewport is larger than the image.
The width of the viewport specifies by how much to zoom in or out of the image, but it does not specify where on the image the viewport is positioned. To specify the viewport position, use the ViewportOrigin.
ZoomAboutLogicalPoint Method
This method enables zooming and panning on the MultiScaleImage, relative to a specified logical coordinate. This method takes a zoomIncrementFactor, a double that indicates by how much to change the existing zoom level.
UseSprings Property
The UseSprings property is used to enable or disable the animations that occur transitioning to a new zoom level or panning, such as when ZoomAboutLogicalPoint is called. The default value is true.
AllowDownloading Property
The AllowDownloading property can be used to halt downloading of image data at any time. This can be useful for halting bandwidth usage when leaving a Wi-Fi connected area.
MotionFinished Event
The MotionFinished event is raised when a zoom or pan animation ends. This event can be used as an alternative to data binding to the ViewportOrigin and/or ViewportWidth properties because sometimes change events fail to be raised when using these properties.