User Manual for Kakadu’s “kdu_show” Tool (last updated for version v4.1) David Taubman, UNSW December 4, 2003 1 1.1 Basic Operations Opening and Closing Files The File menu may be used to open and close Þles. Alternatively, you may Þnd the “o” accelerator key useful for opening Þles quickly. Opening a new Þle automatically closes any existing open Þle. You can supply the name of a Þle to “kdu-show ” on the command line, in which case that Þle will be opened on start up and its dimensions will guide the initial size of the view window. The “kdu-show ” tool can open JP2 Þles, JPX Þles and unwrapped JPEG2000 codestreams. At some point in the future, MJ2 Þles will most likely be added to this list. 1.2 Panning, Zoom and Re-orienting The “kdu-show ” tool started out as a sophisticated demonstration application to showcase some of Kakadu’s capabilities for incremental decompression of large images, based on spatial regions of interest (view ports), as well as Kakadu’s ability to decompress images in a geometrically transformed domain. In fact, Kakadu’s codestream management architecture has always allowed compressed JPEG2000 images to be accessed as though they had been compressed as smaller image, rotated and/or cropped versions of themselves. As a result, the core “kdu-show” features have always been those of panning, zooming, rotating and ßipping a viewport into the compressed image. Panning may be accomplished via the scroll-bars, or using the arrow keys. The PageUP and PageDown keys may also be used for panning. The image may also be dragged around with the mouse while the left mouse button is depressed and the shift key held down. Zooming may be accomplished via the View menu, or with the “z” (zoom in) and “ctrl-z” (zoom out) accelerators. By default, zooming is centred about the middle of the current viewport, but you may deÞne an alternate focus box using the method described below. Zooming out is accomplished using the multi-resolution attributes of the discrete wavelet transform (DWT). As such, 1 c °Taubman, 2001 User Manual for “kdu_show" Page 2 the degree to which you can zoom out is limited by the number of DWT levels created when the image was compressed. Although this limit could readily be circumvented by rescaling the decompressed image, it provides useful feedback to content creators, making them aware of the limitations associated with using too few DWT levels. Rotation and ßipping may be accomplished via the View menu, or with the “[”, “]”, “_” and “|” accelerators. Note, however, that any rotation which involves image transposition (not just horizontal and vertical ßipping) may slightly alter the displayed imagery if it happens to have been compressed using JPEG2000’s reversible processing path (Kakadu’s “Creversible=yes” attribute). The reason for this is that horizontal and vertical aspects of the wavelet transform do not completely commute when the reversible transform is used, due to LSB rounding eﬀects. Kakadu accomplishes rotation by decompressing the imagery in a reverse order and performing the wavelet transform in an alternate order, rather than just decompressing the image and then subsequently reorienting it. The application automatically resizes its window to match the image size, unless the image is too large to be viewed in the current window, in which case a restricted viewport is displayed. You may adjust the window size via the usual resize handles. Alternatively, and often more conveniently, you may enlarge or shrink the view window quickly using the “w” and “s” accelerator keys. 1.3 Focus Boxes Focus boxes have at least 3 uses in “kdu-show ”: 1) they deÞne a centre for zooming; 2) they deÞne the region of interest during remote image browsing with JPIP (see Section 3); and 3) they deÞne spatial regions to be associated with metadata added using the methods described in Section 5. To deÞne a focus box, left click the mouse within the view window, drag the focus box, and then left click again to complete the box. If your mind after the Þrst mouse click, you may hit the right mouse button, or the escape key. This will leave any previously existing focus box intact. To remove a focus box, you may do any of the following: 1) double-click in the view window; 2) use the Focus menu; or 3) hit the “f” accelerator key. By default, the focus box will be displayed using both a highlighting technique and a dashed outline. The highlighting technique makes the rest of the image slightly darker, and the focus box slightly lighter. You can turn oﬀ the highlighting by using the Focus menu, or hitting the “h” accelerator key. You can widen or shrink an existing focus box using the Focus menu, or the “shift-w” and “shift-s” accelerators. You can pan the focus box using the arrow keys, while holding down the shift key. Basically, the accelerators which aﬀect the focus box are identical to those used to manipulate the view window, except that the shift key is held down. c °Taubman, 2001 1.4 User Manual for “kdu_show" Page 3 Quality Layers JPEG2000 codestreams may contain multiple embedded image qualities, which form the foundation of quality progressive remote image browsing. By default, local Þles are opened at maximum quality, but it can be useful to see the visual quality associated with each compressed quality layer. To reduce the number of quality layers you may use the Quality menu or the “<” accelerator. You may increase the quality again using the Quality menu using the “>” accelerator. These manipulations automatically change the status bar to one which displays the number of quality layers which are in use. 1.5 Navigating Between Image Elements The “kdu-show” tool has 3 fundamental modes of image display, as follows: Single Component Mode: In this mode, only a single image component is displayed as a greyscale image. Image components typically correspond to colour channels (e.g., red, green, blue, or luminance, and chrominance channels), but they may correspond to alpha blending channels, palette indices, or anything else. To enter single component mode, use the View menu or hit either of the “1” or “+” accelerator keys. While in this mode, you may navigate forward and backward within the image components of a given codestream by using the View menu or the “+” and “-” accelerators. While in single component mode, you may navigate amongst the codestreams in the Þle (JPX Þles may have any number of codestreams) using the RETURN and BACKSPACE keys. Alternatively, you may use the View menu. Single Compositing Layer Mode: In this mode, only one compositing layer is displayed, usually as a colour image, or alpha blended against a solid white background. A JP2 Þle contains exactly one compositing layer, which is the rendered colour image. A JPX Þle may contain any number of compositing layers. A raw codestream is treated as having exactly one compositing layer, corresponding to our best guess regarding the intended display image. To enter single compositing layer mode, use the View menu or hit the “L” accelerator key. While in this mode, you may navigate forward and backward amongst the compositing layers by using the RETURN and BACKSPACE keys, or the View menu. Composited Image Mode: In this mode, the application displays what it believes to be the intended image. For JP2 Þles and unwrapped raw codestreams, this is identical to the result displayed in single compositing layer mode. If a JPX Þle contains a composition box, however, the composition instructions are used to build the composited image which was intended by the content creator. c °Taubman, 2001 User Manual for “kdu_show" Page 4 When a new Þle is opened, “kdu-show” starts out in the composited image mode, but if you have changed the mode to single component or single compositing layer mode, you may get back to composited image mode by using the View menu or hitting the “c” accelerator. While in composited image mode, you may navigate forward and backward between composited frames (animations contain multiple frames, each of which is a composited image) by using the RETURN and BACKSPACE keys, or via the View menu. 2 Status Information Some summary information is displayed at the bottom of the application window on its status bar. The status bar is divided into Þelds. The information displayed in these Þelds also depends upon the status mode, which may be toggled using the Status menu, or via the “t” accelerator key. In particular, you can currently toggle between the following three status modes: 1. Left Þeld displays current zoom factor (percent) and image element; right Þeld displays the number of quality layers. The image element depends on the image display mode. In single component mode, the component index and codestream index are displayed here; in single compositing layer mode, the compositing layer index is dispayed here; in composited image mode, the animation frame index is displayed here. 2. Left Þeld is as above; right Þeld displays the full size of the image at the current resolution, measured in pixels. 3. Left Þeld displays the amount of working memory used by the codestream management machinery (for all codestreams currently loaded into memory). This value is generally very small if the codestreams are enabled for random access (precincts, PLT marker segments and a layer-minor progression order). 4. (available only when connected to a JPIP server): left Þeld displays active/idle transmission status (idle when all requested imagery for the current view/focus window has been received); centre Þeld displays the total number of bytes received from the server; right Þeld displays the average data rate at which transmitted bytes have arrived, averaged only over non-idle periods. 3 Remote Image Browsing with JPIP By and large, images may be accessed remotely from a JPIP server (such as that implemented by the “kdu-server ” utility) exactly as if they were local Þles. Rather than experiencing signiÞcant delays while the image downloads, you will instead observe incrementally improving quality as image data is incrementally c °Taubman, 2001 User Manual for “kdu_show" Page 5 transferred by the server. JPIP servers focus the transmitted data around the region deÞned by the focus window so the quality in that region increases more rapidly. If no focus window is deÞned, it is taken to be the current view window. Once suﬃcient data has been received to reconstruct the image within the focus window without loss, at the current display resolution, the server enters the idle mode and will not transmit any further data until the image region, resolution (zoom factor), codestream, image components, compositing layer or animation frame are changed. It is important to realize that the viewing tool is only loosely (asynchronously) coupled to the client component and, ultimately, to the server utility. You are always free to pan, zoom and otherwise navigate the display to any part of the image, regardless of whether any data has been received from the server to render that region. After some time, the server will adjust its transmission pattern to serve the new image region/resolution which is currently of interest. Of course, if the server has disconnected, no amount of navigation will bring in new data, so you will generally be left with non-uniform image quality which reßects the amount of time spent browsing in diﬀerent image regions. It is also important to realize that the JPIP server is allowed to shrink the region of the image for which it will serve data, if the region is too large to be served in a quality progressive fashion without consuming excessive server memory resources. If this happens, the changed region will be reßected on the view window through a new focus box. You may move this modiÞed focus box around, to change the region to which the server’s transmission is customized, but you may not enlarge the focus box without having the server force it back down again to its size limit. 3.1 Regular Image Browsing To open a remote image, use the File->OpenURL menu item, or start “kdushow” with an appropriate URL on the command line. The File->OpenURL dialog box provides several Þelds for you to Þll out. For regular image browsing, enter the name of the Þle you want to access in the “Object requested from server” Þeld and enter the name or IP address of the server machine in the “Server name or address” Þeld. You may append an optional colon-separated port number to the server name or address, if your server is not listening on the default port 80. One of three closely related JPIP transfer protocols may be selected via the “Channels and Sessions” drop-down list. For the most eﬃcient communication, the “http-tcp” option is recommended; however, this requires the establishment of both an HTTP and a regular TCP channel, which might not be permitted by some institutional Þrewalls. In this case, select “http” as the next best option. The “none” option is primarily for experimental purposes. It is much less eﬃcient, especially for the server. If your organization requires all external traﬃc to ßow through an HTTP proxy, select the “http” option and put the name or address of your HTTP proxy server in the “Proxy name” Þeld — you may need to consult your system c °Taubman, 2001 User Manual for “kdu_show" Page 6 administrator to Þnd out the name of your HTTP proxy. Proxies reduce the communication eﬃciency and responsiveness, so use them only if necessary. You may elect to have all your image browsing results saved in a local cache directory, by entering the name of this directory into the “Cache dir” Þeld. The advantage of this is that when you open the same image again on the same server, or a compatible server (one which assigns the same unique target identiÞer to the image resource), the previous browsing results will be reused and that data will not be sent over again by the server. An alternate way to open an image on a remote JPIP server is to supply the URL on the command line. The URL must commence with either “http:// ” or “jpip:// ” as the protocol identiÞer preÞx, followed by the server host name (or IP address), a single “/” character, and then the resource string. The synax for the resource string and the server name are identical to those used by the File>OpenURL dialog box. The alternate “jpip:// ” protocol identiÞer is provided so that the “kdu-show ” utility can be Þred up automatically from a web browser whenever a URL with this protocol identiÞer is encountered. In fact “kdu-show ” registers itself with the Windows Internet Explorer as the target for such URLs, the Þrst time it is ever used. You should be aware that when URLs are supplied on the command line, “kdu-show ” obtains the remaining information (proxy server, cache directory, protocol variant) from the registry, based on the last values supplied via the File->OpenURL dialog. For this reason, it is advisable to use this dialog to conÞgure the application Þrst, before opening URL’s from the command line or by clicking on JPIP URLs on a web page. You may explicitly disconnect from a JPIP server, without actually closing the image, by using the File->Disconnect menu item. 3.2 One-Shot Image Browsing To implement the functionality of an image browser, “kdu-show” uses Kakadu’s kdu-client object to generate a sequence of much more complex HTTP requests than that supplied via a typical command line URL. These much richer requests are generated using either HTTP POST or HTTP GET with query parameters appended to the URL, separated by the usual “?” query separator. As an alternative to interactive image browsing, you may supply one of these more complicated URLs directly by including the “?” query separator and the query Þelds of interest. In this case, only one request will be delivered to the server and no amount of interactive navigation within the image will cause any further requests to be sent to the server. The server will continue to transmit data relevant to the original request until all relevant information has been sent or the server times out or is disconnected. As a result, interactive navigation and image data delivery are entirely disconnected processes; you may be receiving data relevant to a small image region at high resolution, but be viewing the image at low resolution (zoom factor) or vice-versa. You may even be viewing a completely diﬀerent codestream within the data source and so not see the eﬀects of newly arrived image data. The main purpose of this mode of behaviour is for server debugging and for c °Taubman, 2001 User Manual for “kdu_show" Page 7 modeling the behaviour of JPIP when all imagery is generated in response to a static URL, which might be embedded in an HTML page. You may also enter single-shot URLs via the File->OpenURL dialog. To do so, simply append the “?” query separator and relevant query parameters to the string enterered in the “Object requested from server” Þeld of the dialog box. To use single shot URLs you will need to be familiar with the JPIP syntax. It is not the purpose of this document to describe this syntax, but the JPIP committee draft may be downloaded from “http://www.jpeg.org/CDs15444.html.” You may also examine the JPIP requests delivered to the Kakadu server during normal interactive image browsing by supplying the ‘-record’ command line option to “kdu-server ”. 4 Viewing Codestream and File Properties Use the File->Properties menu item or the “p” accelerator to view the properties of the current codestream. Where more than one codestream is involved in the current image display, the application chooses one of them to display its attributes. Codestream properties include comment marker segments, coding parameter marker segments and tiling attributes. You may double-click on any attribute to read a detailed description of that attribute’s interpretation, as provided by the Kakadu core system. Additional attributes are provided by the Þle format in which codestreams are embedded. To examine the Þle format itself, use the View menu or the “m” accelerator to activate the “metashow” tool. You may click on various nodes within the metashow tool’s tree view to obtain additional details or to navigate to have the main window navigate to corresponding image elements. For example, clicking on the second compositing layer header box will cause the main window to enter single compositing layer mode and display the second compositing layer. Clicking on a contiguous codestream box or codestream header box will cause the main application to enter single component mode, while clicking on the composition box, if any, will cause the application to enter the composited image mode. Clicking on some leaf nodes in the metadata tree will cause their contents to be expanded as text, while for other boxes a generic hex dump is provided. 5 Metadata Overlays and Editing As of Kakadu v4.1, you may use “kdu-show” to edit and display spatially sensitive metadata in a JPX Þle. You may also add metadata to a JP2 Þle and resave it as JPX. To add metadata use the Edit menu or the “a” accelerator. This opens up the metadata editing dialog, which allows you to enter an arbitrary text label. If no focus box has been selected, the metadata will be associated by default with c °Taubman, 2001 User Manual for “kdu_show" Page 8 the top-most current image entity (compositing layer or codestream), depending on the current image display mode (see Section 1.5). If a focus box was selected when you hit the “a” accelerator, the metadata will be associated by default with the top-most codestream which overlaps with the focus region; it will also be associated explicitly with that region. These associations are achieved by embedding appropriate number list and ROI description boxes in the JPX Þle (when you save the edited result). You may alter any of the above associations within the metadata editing dialog. It will explicitly exclude options which are illegal. For example, metadata associated with a focus region must also be associated with at least one codestream, not just with compositing layers. You will see that you can add multiple associations, but it is up to you to ensure that this is meaningful. Once you have some spatially associated metadata, you will notice that “kdushow” highlights its presence via partially transparent overlays. You may use the Overlay menu to control the appearance of such overlays. Most usefully, the “ctrl-o” accelerator may be used to toggle the overlay mode between flashing, static, and no overlays. You may also control the darkness/lightness of overlays via the Overlay menu, or by using the “ctrl-d” and “ctrl-b” accelerator keys. Finally, you may control the minimum size of elements which will appear on overlays. In the ßashing or static overlay mode, try holding the control key down and moving the mouse cursor over regions which are associated with metadata. You will notice that the cursor changes to one which contains an “M” and the application displays temporary labels where appropriate. Keeping the control key down, you may also left click to open up the metadata editor again. This allows you to modify or delete existing metadata. 6 Saving Files You may save images back out of “kdu-show ” using the File->Save menu item. This is of interest particularly if you have edited the image’s metadata or if the image has been obtained from a remote JPIP server — in that case, the saved Þle will contain whatever information had been received from the server up to the point when it is saved. You may edit and resave a Þle over the top of the Þle you already have open. In this case, however, the Þle is actually saved under a diﬀerent name, formed by appending the “~” character to the name of the currently open Þle rather than overwriting it. When you close the open Þle, any such saved copy is automatically renamed so as to replace the one you had open. This happens even if you close the application (by any of the usual means, or by hitting the “q” accelerator).