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


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 (43)

  1. In our most recent release of Deep Zoom Composer, one of the major changes we made was to change how

  2. SoulSolutions says:

    Awesome, thanks for the introduction, it makes all the difference.

    Now we can do some very cool things with exisiting image collections :)

  3. Yesterday I saw that the Expression Blend and Design team had blogged about the new DeepZoomTool.dll

  4. Dr YSG says:

    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).

  5. Happy Thanksgiving everyone! In this issue: Martin Mihaylov, Tim Heuer, Katrien De Graeve, Expression

  6. George Bell says:

    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!

  7. George Bell says:

    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?

  8. Kirupa (MS) says:

    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.

  9. Kirupa (MS) says:

    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

  10. marauderz says:

    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.

  11. Kirupa (MS) says:

    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

  12. Marauderz says:

    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.

  13. DJ says:

    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.

  14. Kirupa (MS) says:

    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.

    :)

  15. George Bell says:

    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…

  16. Kirupa (MS) says:

    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.

    :)

  17. George says:

    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?

  18. mytsingh says:

    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. 😀

  19. Can I distribute DeepZoomTools.dll with my application?

    If so, can I get a signed version?

    Thank you

  20. Oh and Kirupa,

    I saw the same thing untill I specified a subdirectory for the target files:

    ic.Create(imgFileName, imgFileName.Replace(".jpg", "_files") + "\" + Path.GetFileName(imgFileName).Replace(".jpg", ".xml"));

  21. John says:

    I’ve got a repeatable bug, and I can’t understand it.  For testing, I’ve got the same version of an image created with a width of 100, 250, 500 and 1000 pixels.

    I’m using SparseImageCreator to create a horizontal row of the same images, iterating from 1 to 100 copies of the image.  When I use the 100 pixel image, it works for every iteration.  however, when I use the 250 or 500 pixel image size, it fails on with 20, 24, 49, 83 and 99 copies of the image.  It’s the same results every time.  The error is:

    Very weird!  I can’t find any pattern with these images, and it’s not a memory issue, as I am forcing GC to ensure that memory use never gets too high.  

  22. John says:

    I’ve got a repeatable bug, and I can’t understand it.  For testing, I’ve got the same version of an image created with a width of 100, 250, 500 and 1000 pixels.

    I’m using SparseImageCreator to create a horizontal row of the same images, iterating from 1 to 100 copies of the image.  When I use the 100 pixel image, it works for every iteration.  however, when I use the 250 or 500 pixel image size, it fails on with 20, 24, 49, 83 and 99 copies of the image.  It’s the same results every time.  The error is:

    Very weird!  I can’t find any pattern with these images, and it’s not a memory issue, as I am forcing GC to ensure that memory use never gets too high.  

  23. John says:

    I’ve got a repeatable bug, and I can’t understand it.  For testing, I’ve got the same version of an image created with a width of 100, 250, 500 and 1000 pixels.

    I’m using SparseImageCreator to create a horizontal row of the same images, iterating from 1 to 100 copies of the image.  When I use the 100 pixel image, it works for every iteration.  however, when I use the 250 or 500 pixel image size, it fails on with 20, 24, 49, 83 and 99 copies of the image.  It’s the same results every time.  The error is:

    Very weird!  I can’t find any pattern with these images, and it’s not a memory issue, as I am forcing GC to ensure that memory use never gets too high.  

  24. John says:

    I’ve got a repeatable bug, and I can’t understand it.  For testing, I’ve got the same version of an image created with a width of 100, 250, 500 and 1000 pixels.

    I’m using SparseImageCreator to create a horizontal row of the same images, iterating from 1 to 100 copies of the image.  When I use the 100 pixel image, it works for every iteration.  however, when I use the 250 or 500 pixel image size, it fails on with 20, 24, 49, 83 and 99 copies of the image.  It’s the same results every time.  The error is:

    Very weird!  I can’t find any pattern with these images, and it’s not a memory issue, as I am forcing GC to ensure that memory use never gets too high.  

    Here is the complete error:

    System.ArgumentOutOfRangeException: The parameter value must be greater than zero.

    Parameter name: pixelWidth

      at System.Windows.Media.Imaging.RenderTargetBitmap..ctor(Int32 pixelWidth, Int32 pixelHeight, Double dpiX, Double dpiY, PixelFormat pixelFormat)

      at Microsoft.DeepZoomTools.BitmapTransformer.CloseOutputImpl(OutputNode outputNode)

      at Microsoft.DeepZoomTools.BitmapTransformer.Execute()

      at Microsoft.DeepZoomTools.SparseImageCreator.Create(ICollection`1 images, String destination)

    If I look in the deepzoom folders, it gets to folder 10 before the error.

    Ideas?  Is there a newer version I can test?

    John

  25. JTH says:

    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

  26. Kirupa (MS) says:

    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

  27. John says:

    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?

  28. Kirupa (MS) says:

    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

  29. In our most recent release of Deep Zoom Composer, one of the major changes we made was to change how

  30. 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.

  31. Kirupa (MS) says:

    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 :)

  32. 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

  33. Kirupa (MS) says:

    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.

    :)

  34. 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.

  35. 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

  36. JTH says:

    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

  37. Michael Schall says:

    Kirupa-

    We are using the DeepZoomTools.dll and for the most part things are working great.   We are dynamically creating images that we would like to have pan/scroll/zoom.  Most of our images work great.  Every once in a while we get an error from the dll concerning pixelWidth or pixelHeight:

    System.ArgumentOutOfRangeException occurred

     Message="The parameter value must be greater than zero. Parameter name: pixelHeight"

     ParamName="pixelHeight"

     Source="PresentationCore"

     StackTrace:

          at System.Windows.Media.Imaging.RenderTargetBitmap..ctor(Int32 pixelWidth, Int32 pixelHeight, Double dpiX, Double dpiY, PixelFormat pixelFormat)

          at Microsoft.DeepZoomTools.BitmapTransformer.CloseOutputImpl(OutputNode outputNode)

          at Microsoft.DeepZoomTools.BitmapTransformer.Execute()

          at Microsoft.DeepZoomTools.SparseImageCreator.Create(ICollection`1 images, String destination)

          at Microsoft.DeepZoomTools.ImageCreator.Create(String source, String destination)

    Our code using ImageCreator is below:

    Dim imageCreator As New Microsoft.DeepZoomTools.ImageCreator()

    imageCreator.TileFormat = Microsoft.DeepZoomTools.ImageFormat.Png

    imageCreator.Create(imagePath, outputFolder)

    Any thoughts?

    Thanks

    Mike

  38. Michael Schall says:

    My issues with pixelWidth and pixelHeight for specific images went away with the latest release of DeepZoomTools.dll.

    Thanks

    Mike

  39. xeonix says:

    there are a problem with DeepZoomTools.dll:

    ImageCreator after calling Create method does not releases

    the input file, so after generation of DeepZoom files the original image cannot be deleted!!!!!!

    also sometimes it throws an exception:

    [COMException (0x80070018): The program issued a command but the command length is incorrect. (Exception from HRESULT: 0x80070018)]

    i wrote bur report to the official site, but there was no replies!

  40. Andy says:

    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

  41. Kirupa (MS) says:

    Andy – You would use CollectionCreator :)

    The SparseImageCreator is used for sparse images – which is basically the non-collection output that Deep Zoom Composer supports.

    😛

  42. Mars says:

    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.

  43. WebPrgmer says:

    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!