Creating Content: Deep Zoom Tools

The Deep Zoom Tools package contains a pair of command-line utilities (DZConvert.exe and DZCollection.exe) as well as a .NET class library (DeepZoomTools.dll).

Download

Deep Zoom Tools Command Line Utilities

The Silverlight team has made available a pair of sample applications for DeepZoomTools.dll, providing the ability to easily build Deep Zoom Images (DZI) and Deep Zoom Collections (DZC) from the command line.

As parameter driven command line tools, the Deep Zoom Tools command line utilities can be used to easily automate repetitive content creation work flows.

There are two separate utilities. DZConvert.exe converts one or more image files to Deep Zoom Image (DZI) files. DZCollection.exe converts one or more Deep Zoom Images (DZI) into a Deep Zoom Collection (DZC).

DZCollection.exe provides an extremely efficient method to build or re-build a Deep Zoom Collection when adding or removing images, or when only a subset of the images needs to be updated. It eliminates the bulk of the work required to generate the individual image tiled pyramids. DZCollection.exe also provides a reporting option that can be saved to file via command line redirection for further automated processing.

Deep Zoom Composer must be used to create sparse images, but because sparse images are typically built as individual Deep Zoom Images (DZI), DZCollection.exe is an ideal solution for creating a Deep Zoom Collection from previously created sparse images.

Deep Zoom Tools Class Library

DeepZoomTools.dll provides a powerful and simple to use class library for incorporating Deep Zoom Collection creation in your own custom content management applications.

Public Classes and Methods

public enum ImageFormat { Jpg, Png, Wdp, AutoSelect };

JPEG is best for photographic content, while PNG is best for text, art, or images with transparency. JPEG is faster to decode on the client than PNG, so applications might have better performance using JPEG. HD Photo (WDP) is not yet supported by Silverlight Deep Zoom or Seadragon Ajax.

AutoSelect will pick attempt to pick the best format based on the input images. It will only pick HD Photo if the input image is HD Photo.

public class Image

An image to go into a collection or sparse image.

public Image(string path)

Initializes a new instance of the Image class, setting its path. When building a collection, the path can be either the path to an already created image, or the path to an image in a bitmap format such as JPEG, PNG, HD Photo, TIFF, or BMP. When building a sparse image, the path can only be to an image in a bitmap format.

public double MaxViewportWidth

Gets or sets the maximum viewport width. This property applies only when building a sparse image and allows for images to be drawn up to a specific zoom level (defined as a ViewportWidth) and not farther. Default is double.MaxValue.

public double MinViewportWidth

Gets or sets the minimum viewport width. This property applies only when building a sparse image and allows for images to be drawn up to a specific zoom level (defined as a ViewportWidth) and not farther. Default is double.Epsilon.

public string Path

Gets the path for the image.

public Point ViewportOrigin

Gets or sets the viewport origin of the image. For a collection, this property sets the initial viewport origin for an item. For a sparse image, this property sets the viewport origin of where in the sparse image the item should be drawn. Default is (0,0).

public double ViewportWidth

Gets or sets the viewport width of the image. For a collection, this property sets the initial viewport width for an item. For a sparse image, this property sets the viewport width of where in the sparse image the item should be drawn. Default is 1.0.

public class ImageCreator

A class to create Deep Zoom Images from regular images in bitmap formats such as JPEG, PNG, HD Photo, TIFF, or BMP.

public ImageCreator()

Initializes a new instance of the ImageCreator class.

public double ImageQuality

Gets or sets the JPEG quality of the resulting image, between 0.0 and 1.0. This parameter is ignored if the TileFormat is PNG. Default is 0.8.

public int TileSize

Gets or sets the size of the tiles in the resulting image. This should ideally be a power of 2 minus twice the tile overlap; that allows the common-case middle tiles to be exact powers of 2, which improves memory efficiency on the client. Default is 254.

public int TileOverlap

Gets or sets the overlap between tiles in the resulting image. Tile overlap is used to smooth out seams between tiles when images are drawn on the screen. If you zoom in on a tile edge, the seam will be clearly visible unless there is overlap. Default is 1.

public ImageFormat TileFormat

Gets or sets the format of the tiles. See the ImageFormat enumeration for details. Default is AutoSelect.

public bool CopyMetadata

Gets or sets whether to copy the EXIF/XMP metadata to each individual tile. If set to true, each individual tile will be bigger to carry duplicate metadata. Default is false.

public bool ConversionCopyMetadata

Gets or sets whether to copying the EXIF/XMP metadata to each individual image tile when creating a collection from a set of bitmaps (not Deep Zoom images). If set to true, each individual tile will be bigger to carry duplicate metadata. Therefore, the recommendation is to set it to false. Default is false.

public double ConversionImageQuality

Gets or sets the JPEG quality of the images in the collection when creating a collection from a set of bitmaps (not Deep Zoom images). This parameter is ignored if the TileFormat is PNG. Do not use a higher quality for the collection than the input images. Default is 0.8.

public ImageFormat ConversionTileFormat

Gets or sets the format of the image tiles when creating a collection from a set of bitmaps (not Deep Zoom images). See the ImageFormat enumeration for details. Default is AutoSelect.

public int ConversionTileOverlap

Gets or sets the overlap between tiles in the image tiles when creating a collection from a set of bitmaps (not Deep Zoom images). Tile overlap is used to smooth out seams between tiles when images are drawn on the screen. If you zoom in on a tile edge, the seam will be clearly visible unless there is overlap. Default is 1.

public int ConversionTileSize

Gets or sets the size of the image tiles when creating a collection from a set of bitmaps (not Deep Zoom images). Default is 256.

public ServerFormats ServerFormat

Gets or sets the server format of the output collection (and images if images are also being created). See the ServerFormats enumeration for details.

public void Create(string source, string destination)

Creates a Deep Zoom Image at the destination path from the regular image at the source path. The source image must be in a bitmap format such as JPEG, PNG, HD Photo, TIFF, or BMP.

public class CollectionCreator

A class to create Deep Zoom Collections from a set of images.

public CollectionCreator()

Initializes a new instance of the CollectionCreator class.

public double ImageQuality

Gets or sets the JPEG quality of the collection, between 0.0 and 1.0. This parameter is ignored if the TileFormat is PNG. Do not use a higher quality for the collection than the input images. Default is 0.8.

public int TileSize

Gets or sets the size of the collection tiles, which must be a power of 2 and can't be smaller than the tile sizes of the input images. Default is 256.

public int MaxLevel

Specifies the maximum level included in a collection. Default is 7.

public ImageFormat TileFormat

Gets or sets the format of the collection tiles. See the ImageFormat enumeration for details. Default is AutoSelect.

public bool CopyMetadata

Gets or sets whether to copying the EXIF/XMP metadata to each individual collection tile. If set to true, each individual tile will be bigger to carry duplicate metadata. Therefore, the recommendation is to set it to false. Default is false.

public void Create(ICollection<Image> images, string destination)

Creates a Deep Zoom Collection from the list of images and writes it to the destination file. Each item in the list is an Image object representing either an already created Deep Zoom Image or a regular image in a bitmap format such as JPEG, PNG, HD Photo, TIFF, or BMP. Additional properties set on the Image object are used as well.

public void Create(ICollection<string> images, string destination)

Creates a Deep Zoom Collection from the list of images and writes it to the destination file. Each item in the list is an Image object representing either an already created Deep Zoom Image or a regular image in a bitmap format such as JPEG, PNG, HD Photo, TIFF, or BMP.

public void Create(ICollection images, string destination)

Creates a Deep Zoom collection from the list of image surrogates and writes it to the destination file. Each item in the list is a SurrogateImageInfo object representing either an already created Deep Zoom image or a regular image in a bitmap format such as JPEG, PNG, HD Photo, TIFF, or BMP. Additional properties set on the Image object are used as well.

public class SparseImageCreator

A class to create sparse Deep Zoom Images from regular images in bitmap formats such as JPEG, PNG, HD Photo, TIFF, or BMP.

public SparseImageCreator()

Initializes a new instance of the SparseImageCreator class.

public double ImageQuality

Gets or sets the JPEG quality of the resulting image, between 0.0 and 1.0. This parameter is ignored if the TileFormat is PNG. Default is 0.8.

public int TileSize

Gets or sets the size of the tiles in the resulting image. This should ideally be a power of 2 minus twice the tile overlap; that allows the common-case middle tiles to be exact powers of 2, which improves memory efficiency on the client. Default is 254.

public int TileOverlap

Gets or sets the overlap between tiles in the resulting image. Tile overlap is used to smooth out seams between tiles when images are drawn on the screen. If you zoom in on a tile edge, the seam will be clearly visible unless there is overlap. Default is 1.

public ImageFormat TileFormat

Gets or sets the format of the tiles. See the ImageFormat enumeration for details. Default is AutoSelect.

public Color BackgroundColor

Gets or sets the color to show in the parts of the sparse image not covered by individual images. Default is white if the tile format is JPEG or transparent if the tile format is PNG.

public bool CopyMetadata

Gets or sets whether to copying the EXIF/XMP metadata to each individual tile. If set to true, each individual tile will be bigger to carry duplicate metadata. Therefore, the recommendation is to set it to false. Default is false.

public void Create(ICollection<Image> images, string destination)

Creates the sparse Deep Zoom Image from the list of regular images and writes it to the destination file. Each item in the list must be an Image object with the path of a regular image in a bitmap format such as JPEG, PNG, HD Photo, TIFF, or BMP. The ViewportOrigin and ViewportWidth properties on the Image object determine where the image should be drawn into the sparse image.

Public Classes and Methods for Events

DeepZoomTools.dll uses events to let code redirect the input or output of DeepZoomTools or learn more about the images being processed. Also, many events have a Progress value that code can use to monitor the progress of DeepZoomTools conversions.

public class DZTEvents

A base class for all the conversion operations that provides the appropriate events.

public DZTEvents()

Not needed.

public event EventHandler CreateDirectory

This event occurs when a new directory is needed to output tiles. Handlers should create the directory if needed by their storage system.

public event EventHandler InputNeeded

This event occurs when a new input file is needed by DeepZoomTools. Use the FileName property to find out which file is needed, open the appropriate object, and set the Stream property to the stream. The Compress and MimeType properties may be helpful to select the appropriate object.

public event EventHandler InputImageInfo

This event occurs when an image has been opened successfully for conversion. Use the information as needed.

public event EventHandler InputCompleted

This event occurs when an input file has been completely read by DeepZoomTools. Close the Stream.

public event EventHandler OutputNeeded

This event occurs when a new output file is needed by DeepZoomTools. Use the FileName property to find out which file is needed, create the appropriate object, and set the Stream property to the stream. The Compress and MimeType properties may be helpful to select the appropriate object.

public event EventHandler OutputInfo

This event occurs when an image has been converted. Use the information as needed.

public event EventHandler OutputCompleted

This event occurs when an output file has been completely read by DeepZoomTools. Close the Stream. The Compress and MimeType properties may be helpful when storing the object.

public class StreamEventArgs

A class to manage parameters in and out of the stream events.

public StreamEventArgs(string fileName)

Not needed.

public bool Compress

Gets or sets whether DeepZoomTools recommends compressing this file. This will be true for XML files and false for image files.

public string FileName

Gets or sets the name of the file that DeepZoomTools wants to read or write.

public string MimeType

Gets or sets the mime type of the file that DeepZoomTools wants to read or write.

public double Progress

Gets or sets the amount of progress that DeepZoomTools has made on the conversion from 0 to 100.

public Stream Stream

Gets or sets the stream which DeepZoomTools should read or write.

public class ImageInfoEventArgs

A class to manage parameters into the ImageInfo events.

public Point Dpi

Gets the dots per image of the image.

public string FileName

Gets the name of the file.

public PixelFormat ImagePixelFormat

Gets the pixel format of the image.

public Point PixelSize

Gets the size of the image in pixels.

public class OutputInfoEventArgs

A class to manage parameters into the ImageInfo events.

public Point Dpi

Gets the dots per image of the image.

public string FileName

Gets the name of the file.

public ImageFormat Format

Gets the image format of the image.

public int MaxLevel

Gets the maximum level of the image.

public int NumTiles

Gets the count of tiles in the image.

public PixelFormat ImagePixelFormat

Gets the pixel format of the image.

public Point PixelSize

Gets the size of the image in pixels.

Additional Public Classes and Methods for Events

The following classes should not be used: FileLog, PhotoCollectionCreator