Hello DeepZoomTools.DLL : Deep Zoom Image Tile Generation Made Easy

  • Article

In our most recent release of Deep Zoom Composer, one of the major changes we made was to change how we generated the image tiles both for designing as well as exporting your Deep Zoom Content. In the past, ever since our first release at MIX, our image encoding was done using a combination of SparseImageTool.exe and ImageTool.exe command line tools. Starting with this release, we have retired those tools and have shifted to a preview version of a .NET based DLL that provides image generation capabilities.

If you look inside your Deep Zoom Composer installation folder, which is by default, [Program Files]\Microsoft Expression\Deep Zoom Composer, you will see a file called DeepZoomTools.dll:

 dztoolsPNG

This DLL contains all of the functionality needed for you to generate image tiles for compositions and collections. The classes and methods that you can use are as follows:

public enum ImageFormat { Jpg, Png, Wdp };

public class Image     public Image(string path)     public double MaxViewportWidth     public double MinViewportWidth     public string Path     public Point ViewportOrigin     public double ViewportWidth

public class ImageCreator     public ImageCreator()     public double ImageQuality     public int TileSize     public int TileOverlap     public ImageFormat TileFormat     public bool CopyMetadata     public void Create(string source, string destination)

public class CollectionCreator     public CollectionCreator()     public double ImageQuality     public int TileSize     public int MaxLevel     public ImageFormat TileFormat     public bool CopyMetadata     public void Create(ICollection<Image> images, string destination)     public void Create(ICollection<string> images, string destination)

public class SparseImageCreator     public double ImageQuality     public int TileSize     public int TileOverlap     public ImageFormat TileFormat     public Color BackgroundColor     public bool CopyMetadata     public void Create(ICollection<Image> images, string destination)

The API should be pretty straightforward. A DeepZoomTools.Image is the internal notion of a Deep Zoom image, and it contains all of the information such as the viewport widths, path to source image, origin, etc. ImageCreator is used to define an image and write the image tiles to disk. CollectionCreator and SparseImageCreator take a list of image paths and write the image tiles to disk.

When I was playing with this, the one thing that confused me was what CollectionCreator expected as its “image path”. It isn’t a string of paths to raw JPG, PNG, etc. files. It is actually a path to the Deep Zoom Image created via ImageCreator/SparseImageCreator. SparseImageCreator does take in a list of paths to the source image, so passing in a list of image files will work for generating sparse images (aka Compositions).

Do note that this DLL is a pre-release version, and the Live Labs team will decide when and how to more formally release this in the future. Even though Deep Zoom Composer uses this same DLL, there may be future releases of this DLL that are independent of Deep Zoom Composer releases.

Thanks,
Kirupa

Comments

  • Anonymous
    November 26, 2008
    In our most recent release of Deep Zoom Composer, one of the major changes we made was to change how

  • Anonymous
    November 26, 2008
    Awesome, thanks for the introduction, it makes all the difference. Now we can do some very cool things with exisiting image collections :)

  • Anonymous
    November 27, 2008
    Yesterday I saw that the Expression Blend and Design team had blogged about the new DeepZoomTool.dll

  • Anonymous
    November 27, 2008
    The new DLL is much faster, and yes, this is an improvement. But I am it still fails about about image 80 when I try and load a 100 image project I created in an earlier version (100 tiles of 8K x 8K JPEG).

  • Anonymous
    November 27, 2008
    Happy Thanksgiving everyone! In this issue: Martin Mihaylov, Tim Heuer, Katrien De Graeve, Expression

  • Anonymous
    November 27, 2008
    Works great! However, I was thinking with this new setup I could parallelize the imagecreation part of the process...I used the Parallel extensions library and it works fine (90% cpu instead of 45%) as long as I don't enable copymetadata=true. When I enable this I get Cannot Write to Stream - {"Exception from HRESULT: 0x88982F71"} when calling the create method. Wondering if there is a way around this, I realize it has to do with STA and COM, but it sure would be nice to be able to do this. Thanks!

  • Anonymous
    November 27, 2008
    Another question... I am getting an ArgumentOutOfRangeException on imagecreator.create() "Index was out of range. Must be non-negative and less than the size of the collection.rnParameter name: index" Works fine for about 400 images and then throws that... Any ideas why this would be happening?

  • Anonymous
    November 27, 2008
    YSG - are you using Deep Zoom Composer or a custom app that directly talks to the DLL? If you are using Deep Zoom Composer, is the actual arrangement of images really important, or would a generic grid-like view suffice? The reason I ask is that I have a prototype of an application that just takes a folder of images, makes a collection out of it, and displays the images in a grid set programmatically. George - I am assuming that you are using a custom app for accessing the DLL. We have using the Parallel Extensions Library in the back of our list of things to do, but I haven't actually played with it enough to give you a better idea of why that error is being thrown. Is Copying Metadata something that is important to you? Generally, this is useful for copyright scenarios where each image tile would contain the licensing information. Also, Copying Metadata only works for JPEG files. PNG files are not supported yet. For your second question, I am really not sure what the answer would be. I will forward your question to a colleague who may know more, but because this is a holiday weekend for many of us, it may not be until early next week you get a response back.

  • Anonymous
    November 27, 2008
    George - Would it be possible for you to post that image somewhere I can access? If not, feel free to e-mail it to me at kirupa@kirupa.com. Thanks, Kirupa

  • Anonymous
    November 30, 2008
    Hey guys... so if I make a program that makes use of the DLL... can I redistribute the DLL with the program? Cause I don't see it being installed in the GAC right now. Or I guess I could do it the roundabout way and tell the user to install DeepZoom Composer first, and then my program will go and look for the DLL to copy into the local application folder.

  • Anonymous
    November 30, 2008
    Hi marauderz, This DLL is still a beta/pre-alpha version of what the Live Labs team is planning on doing in the future. While you can distribute the DLL with your app, do note that the DLL will be getting outdated very fast as we keep making updates and changes to it. Thanks, Kirupa

  • Anonymous
    November 30, 2008
    Well, all I need right now is for it to generate images and collections, so that's good enough for me! thanks for the info.

  • Anonymous
    December 02, 2008
    Hi Kirupa, I do appreciate giving me a great product! I'm very happy with ImageCreator. Unfortunately, When i try to gerenate images using ViewportOrigin property with SparseImageCreator, i got "Image out of bounds" error. here is a simple codes. Microsoft.DeepZoomTools.SparseImageCreator s = new Microsoft.DeepZoomTools.SparseImageCreator(); s.CopyMetadata = false; s.TileFormat = Microsoft.DeepZoomTools.ImageFormat.Jpg; List<Microsoft.DeepZoomTools.Image> l = new List<Microsoft.DeepZoomTools.Image>(); double x = 0; foreach (FileInfo p in fies) {  Microsoft.DeepZoomTools.Image i = new Microsoft.DeepZoomTools.Image(p.FullName);  i.ViewportOrigin = new System.Windows.Point(x, x);  l.Add(i); x += 0.1; } s.Create(l, Environment.CurrentDirectory + "\b.xml"); Could you please let me know how can i generate several images to deepzoom images.

  • Anonymous
    December 06, 2008
    DJ - if you try multiplying the argument for y by -1, do you still get that error? I haven't played with SparseImageCreator a great deal, so I don't know for sure how to debug your problem yet. :)

  • Anonymous
    December 07, 2008
    I'll try to send the files this week... Another nice addition would be a callback/event for the collectioncreator.create method to return status...it can take a long time to run so b eing able to inform the user where we are in the process would be great...

  • Anonymous
    December 07, 2008
    George - that is actually a great suggestion! I will see what I can do about possibly supporting a callback on cc.create() to provide progress. :)

  • Anonymous
    December 08, 2008
    Another thing I noticed, for large collections the cc.create() uses a huge amount of ram (for 10,000 images it gave me out of memory errors - it looked to be at about 2 gigs of ram, 8 gigs of swap)...is it trying to load all the images into memory at once?

  • Anonymous
    December 25, 2008
    Hi Kirupa, I got a problem here: I run these simple codes and it work:   Microsoft.DeepZoomTools.ImageCreator ic = new ImageCreator();   ic.Create("E:\ample.jpg", "E:\Sample.xml"); The problem is that after running this, I can't operate the original photo "E:\ample.jpg" any more, for example to rename it. OS says that the photo was operating by other proceeds. I stop the "Asp.Net Development Server", then it can be renamed. So would you tell me where the mistake is ? How can I dispose it? my email is mytsingh#hotmail.com. waiting for good news,sorry for bad english. :D

  • Anonymous
    January 01, 2009
    Can I distribute DeepZoomTools.dll with my application? If so, can I get a signed version? Thank you

  • Anonymous
    January 01, 2009
    Oh and Kirupa, I saw the same thing untill I specified a subdirectory for the target files: ic.Create(imgFileName, imgFileName.Replace(".jpg", "_files") + "&quot; + Path.GetFileName(imgFileName).Replace(".jpg", ".xml"));

  • Anonymous
    January 13, 2009
    The comment has been removed

  • Anonymous
    January 13, 2009
    The comment has been removed

  • Anonymous
    January 13, 2009
    The comment has been removed

  • Anonymous
    January 13, 2009
    The comment has been removed

  • Anonymous
    January 14, 2009
    First of all: THANKS for the DLL. I needed it for my project to generate DZ files! Though, I do have a problem with it. The DLL leaves the files it works with open. This is somehow bad as I have to delete the original file from which the DZ files where created from. Sometimes it helped to run the GC, but sometimes it doesn't. Here the code: var name = @"C:WindowsTEMP63216442-36e2-42b7-9986-b5d43ce89bebtmpfile.jpg"; var root = @"C:/TestGeneratedImages"; var output = Path.Combine(root, Path.GetFileNameWithoutExtension(name) + ".xml"); var creator = new ImageCreator{ TileFormat = ImageFormat.Jpg, TileOverlap = 1, TileSize = 256 }; creator.Create(name, output); var ccreator = new CollectionCreator {    TileFormat = ImageFormat.Jpg,    TileOverlap = 1,    TileSize = 256 }; ccreator.Create(new List<string> { output }, Path.Combine(root, "dzc_output.xml")); creator = null; ccreator = null; System.GC.Collect(); -> File is still open... Can someone help here? Cheers, Jens

  • Anonymous
    January 15, 2009
    Hi JTH - i e-mailed the developer of this, and he mentions that making another GC.Collect() call should fix this. Let me know if that works. Thanks, Kirupa

  • Anonymous
    January 15, 2009
    Kirupa, I'm glad you are able to help JTH, but you didn't comment on my bug that I presented just before his.  Do you have any thoughts?

  • Anonymous
    January 15, 2009
    John - sorry about that. I get an e-mail notification whenever a comment gets made, and I must have missed the notification for your comment. I will look into your issue and try to post back shortly. If you find that I've forgotten, please feel free to e-mail me directly at kirupac[at]microsoft.com :) Thanks, Kirupa

  • Anonymous
    January 21, 2009
    In our most recent release of Deep Zoom Composer, one of the major changes we made was to change how

  • Anonymous
    January 23, 2009
    Is there a substitute for those that still need to use SparseImageTool.exe? I updated the Composer to get the dll but also need the .exe with older code that we have.

  • Anonymous
    January 23, 2009
    Hi Joaquin, No, there is no substitute for SparseImageTool.exe. We are strongly encouraging users to use this DLL in their projects instead. Is there some functionality that SparseImageTool.exe provided that you can't emulate with the updated DLL? Thanks, Kirupa :)

  • Anonymous
    January 23, 2009
    Is there a signed version of the dll? I'd like to sign my application but can not because the DeepZoomTools.DLL is not strongly siged. Is there a signed vesrion? Thank you, Peter

  • Anonymous
    January 23, 2009
    We currently don't have a signed version of the DLL available publically, I'll make sure that the next release of DZC will contain a signed version of this DLL. :)

  • Anonymous
    January 26, 2009
    Hi Kirupa, The cli access to the tool. We are generating big PNGs (from drawings), a Scene xml file, and a batch script to make SparseImageTool.exe generate the slices of the scene for us.

  • Anonymous
    January 26, 2009
    Hi Kirupa, The cli access to the tool. We are generating big PNGs (from drawings), a Scene xml file, and a batch script to make SparseImageTool.exe generate the slices of the scene for us. Also, I'm trying to use this DLL to add new images to a collection but the DLL is not generating the files that go in the dcz_output_files directory. Is there a way to use this dll to add elements to a scene or do I have to re-create the whole thing and then give it to the dll? Thanks

  • Anonymous
    February 02, 2009
    Kirupa, thanks for the help. Though just adding another GC call did not help, I got it running by adding Thread.Sleep(0) after the first and a second GC call. It seems that this helped to really get rid of the objects that held the files open. Thanks, Jens http://www.finalcandidate.com/en/Pages/imagezoom.aspx

  • Anonymous
    February 16, 2009
    The comment has been removed

  • Anonymous
    February 23, 2009
    My issues with pixelWidth and pixelHeight for specific images went away with the latest release of DeepZoomTools.dll. Thanks Mike

  • Anonymous
    February 24, 2009
    The comment has been removed

  • Anonymous
    May 28, 2009
    hi there - many thanks for this. what is the difference between SparseImageCreator & CollectionCreator ? If I want to create a collection for use in a MSI which should I use ? Cheers, Andy

  • Anonymous
    May 28, 2009
    Andy - You would use CollectionCreator :) The SparseImageCreator is used for sparse images - which is basically the non-collection output that Deep Zoom Composer supports. :P

  • Anonymous
    September 07, 2009
    Hi Kirupa, Thank you for the fantastic job you have done with Deepzoom and Seadragon. I am using the DeepZoomTools.DLL to create the required tiles for my project. Is it possible to create the tiles in a flat hierarchy? So instead of grouping the tiles in the various folders such as 1, 2, 3, 4 etc you would actually rename the tiles as 1_0_0.jpg (where the first digit denotes the tile level.

  • Anonymous
    March 22, 2010
    Hi Kirupa, First off, thanks for the great examples! Any input on this post?? http://forums.silverlight.net/forums/t/169921.aspx Using CollectionCreator.Create seems to be crashing if I have more than 100 jpgs. Any ideas for me to overcome the issue? Or should I be using something other than DeepZoomTools.dll for my requirement? Thanks so much!