jpx_metanode

This object is used to interact with an internal metadata tree, which is created to reflect the associations between metadata in a JPX file. By metadata, here we mean all of the box types described in connection with the jpx_meta_manager::set_box_filter function, plus any association ( asoc) boxes and the first sub-box of any association box. Boxes which are not represented by this object are those which are directly related to rendering the compressed imagery. Typical examples of boxes managed by the object are XML boxes, number list boxes, label boxes, ROI description boxes, UUID boxes and IP-rights boxes.

Each intermediate node in the tree (i.e. everything other than the root and the leaves) corresponds an association relationship, which could be represented using a JPX association ( asoc) box. In some cases, the relationship might be represented by some other means, such as inclusion of the relevant metadata within a codestream header or compositing layer header box, but it is easiest to understand the tree structure by assuming that each intermediate node corresponds to exactly one association box. The first sub-box of an association box plays a special role, describing an entity to which all subsequent sub-boxes are to be associated. These subsequent sub-boxes are represented by the node's descendants (branches in the tree), while the contents of the first box are considered to belong to the node itself.

In cases where the first sub-box of an association is itself an association box, it is usually unclear exactly what association was intended. Ror this reason, we do not include the first sub-box of an association amongst the descendants of a node. All other sub-boxes are treated as descendants (branches) whose nodes may be further split if they contain association boxes.

There are two important cases for the first sub-box of an association box, as follows:

• If the first sub-box of an association is a number list ( nlst) box, all descendants of the node are associated with the image entities listed in the number list box. These entities may be codestreams, compositing layers, or the entire composited image.
• If the first sub-box of an association is an ROI description ( roid) box, all descendants of the node are associated with the rectangular and/or elliptical regions described by that box.

The above two special cases are represented explicitly and the association parameters may be explicitly created, tested and retrieved via the various member functions offered by the jpx_metanode interface.

As mentioned previously, the associations embodied by an intermediate node in the metadata tree might not necessarily arise from the appearance of an asoc box within the JPX file. In particular, wherever any of the metadata boxes mentioned above appears within a codestream header or a compositing layer header box, the metadata will be treated as though it had been contained within an asoc box whose first sub-box was a number list box which referenced the relevant codestream or compositing layer. When the information in a jpx_metanode tree is used to write a new JPX file, however, all associations will be formed using asoc boxes, rather than by inclusion within codestream header or compositing layer header boxes.

Leaves in the tree have no descendants. A leaf node represents a single JP2 box, which is not further divided through the use of asoc boxes.

In the above, we have described intermediate nodes and leaf nodes. The one additional type of node is the tree root, to which access is granted using jpx_meta_manager::access_root. All descendants of the root node correspond to metadata which (at least notionally) resides at the top level of the file. Whereas intermediate nodes have their own box, which corresponds to the first sub-box of an association box (whether real or implied), the root node has no box of its own; it has only descendants.

The jpx_metanode interface is designed to meet the needs of file readers and file writers, including incremental file parsers, which may be accessing a JPX data source which is being supplied by a dynamic cache whose contents are written in some arbitrary order by a remote JPIP server. Both reading and writing functions may be used together to interactively edit an existing metadata tree. For this reason, provision is made to read boxes which are described by any of the methods allowed during writing, including boxes which are described by reference to an existing node (possibly in another metadata tree) and boxes which are described by placeholders which are used to defer box generation until the file is actually being written.

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_metanode (2 forms)

exists {Java: Exists}

operator!

operator==

operator!=

get_numlist_info {Java: Get_numlist_info}

get_numlist_codestreams

get_numlist_layers

get_numlist_codestream {Java: Get_numlist_codestream}

get_numlist_layer {Java: Get_numlist_layer}

test_numlist {Java: Test_numlist}

get_num_regions {Java: Get_num_regions}

get_regions

get_region {Java: Get_region}

get_bounding_box {Java: Get_bounding_box}

test_region {Java: Test_region}

get_box_type {Java: Get_box_type}

get_label {Java: Get_label}

get_existing

get_delayed

count_descendants {Java: Count_descendants}

get_descendant {Java: Get_descendant}

get_parent {Java: Get_parent}

add_numlist {Java: Add_numlist}

add_regions {Java: Add_regions}

add_label {Java: Add_label}

add_delayed

add_copy {Java: Add_copy}

delete_node {Java: Delete_node}