jpx_meta_manager

This object provides access to the metadata tree managed by the jpx_metanode interface. For a thorough discussion of the structure and contents of metadata trees, refer to the extensive comments appearing with jpx_metanode. You should review these concepts before trying to understand the ensuing text. For more information on the exact box types which are represented by the metadata tree, see the set_box_filter function.

In addition to granting access to the metadata tree, the present object adds an additional layer of organization on the metadata, providing efficient access to boxes of interest and facilitating the creation of files whose metadata organization is amenable to efficient access in remote client-server applications.

This additional layer of organization consists of a number of linked lists. Each node in the metadata tree may reside on at most one of these lists, although some nodes might not reside on any list. These lists are not apparent to the application, but it is worth offering some explanation here so that you can appreciate what is going on. The lists may be divided into three types, as described below.

A first type of list serves to link metadata nodes which are represented by an ROI description box. This includes leaf nodes which contain an ROI description box, as well as intermediate nodes whose association box's first sub-box is an ROI description box. The common feature of all these nodes is that the corresponding jpx_metanode::get_num_regions function returns a non-zero number of image regions.

There may be many lists of this first type, which are managed using a scale-space structure. The multi-scale aspects of the structure are generated by dividing the relevant nodes, i, on the basis of a dimension D_i. D_i is the largest dimension of the smallest bounding box which contains all regions in the ROI description box.

• The multi-scale structure is based on a collection of thresholds, T0=0 < T1 < T2 < ... If D_i lies in the range T(k-1) < D_i <= Tk, then node i is associated with scale k. The value of T1 is currently fixed at 8, but there is no need for the application ever to know what this value is and it might easily change in the future.
• Associated with each scale k, is a spatial partition whose dimensions are proportional to the scale threshold, Tk. Each element in the partition has its own list, into which the nodes whose upper left hand corner lies within that partition are inserted.
• To further improve access efficiency, the lists within each scale are further arranged into an hierarchical structure.

The second type of list serves to link all metadata nodes which are represented by a number list. This includes leaf nodes which contain a number list box, intermediate nodes corresponding to association boxes whose first sub-box is a number list box, and intermediate nodes which serve to collect metadata found inside codestream or compositing layer header boxes. The common feature of all these nodes is that the corresponding jpx_metanode::get_numlist_info function returns true. There is currently exactly one of these lists.

A third type of list manages all nodes are not linked into or descended from any node which is linked into either of the list types mentioned above. These nodes represent metadata which is not associated with any specific image entity or image region. Such metadata may be considered to describe properties of the file itself, rather than its imagery. We do not expect to encounter too much of this type of metadata, so only one list is used.

Note that any node which is associated with a number list and/or an ROI description box, but which is not itself a number list or ROI description, will not be linked into any of the lists.

The lists described above have no impact on the way the metadata tree actually appears. They serve only to improve the efficiency with which searches are made for metadata associated with a specific image region or image entity. The relevant searches are facilitated by the enumerate_matches function.

The lists are also used when writing metadata to a JPX file. The idea is that if the lists tend to improve the efficiency with which a file's metadata tree can be searched, then organizing the metadata within each list into a separate top level group of boxes in the file will also be beneficial. In particular, this will help reduce the number of top level boxes whose contents need to be expanded by a JPIP server when delivering metadata to a client — each such box will typically be represented by a JPIP placeholder box.

It is worth knowing that Kakadu's JPX file writer builds these top level groupings by creating association boxes whose first sub-box is a free box. Since the contents of a placeholder are associated only with the first sub-box, and that box has no semantics, this mechanism serves to create groups without any unintended semantic overtones.

It is also worth knowing that some nodes in the metadata tree may have descendants which reside on different lists and hence are included in different top level groups by the Kakadu JPX file writer. Where this happens, the common boxes must be duplicated, either explicitly or by reference, which may create some redundancy in the file.

Note carefully that objects of the jpx_metanode class are merely interfaces to an internal object, which cannot be directly created by an application. Use the member functions offered by jpx_meta_manager to obtain a non-empty interface.

jpx_meta_manager (2 forms)

exists

operator!

set_box_filter

access_root

copy

load_matches

enumerate_matches

insert_node