| synopsis || return value || arguments || prev || next |
jpx_metanode enumerate_matches( jpx_metanode last_node, int codestream_idx, int compositing_layer_idx, bool applies_to_rendered_result, kdu_dims region, int min_size)
[Declared in "../apps/compressed_io/jpx.h"]
This function represents the metadata search facilities of the jpx_meta_manager object. It exploits the lists mentioned in the jpx_meta_manager overview discussion to avoid scanning through the entire metadata tree.
If last_node is an empty interface, the function searches for the first node which matches the conditions established by the remaining arguments.
If last_node is not an empty interface, the function searches for the first node which follows the last_node and satisfies the conditions. For reliable behaviour, any non-empty last_node interface should refer to a node which itself matches the conditions.
You should be aware that the order in which this function enumerates the matching nodes is not generally predictable. In fact, the order may potentially change each time you invoke the load_matches function. In particular, if the file is located on a remote server, delivered via JPIP, you may need to call load_matches frequently, and after each call the only way to enumerate all metadata which matches some criterion is to start from scratch, calling this function first with an empty last_node interface and then until it returns an empty interface.
To understand the constraints imposed by the various arguments it is convenient to define three types of nodes:
The function matches only those nodes which belong to one of the above three categories. It matches "ROI Nodes" if and only if region is a non-empty region. It matches "Numlist Nodes" if and only if region is an empty region and either codestream_idx>=0, compositing_layer_idx>=0 or applies_to_rendered_result=true. It matches "Unassociated Nodes" if and only if codestream_idx=-1, compositing_layer_idx=-1, applies_to_rendered_result=false, and region is an empty region.
An empty interface if no match can be found.
If non-negative, the function matches only "Numlist Nodes" which reference the indicated codestream index or "ROI Nodes" which have a "Numlist Node" in their ancestry which references the indicated codestream index. The latter case applies only if region is non-empty.
If non-negative, the function matches only "Numlist Nodes" which reference the indicated compositing layer index or "ROI Nodes" which have a "Numlist Node" in their ancestry which references the indicated compositing layer index. The latter case applies only if region is non-empty.
If true, the function matches only "Numlist Nodes" which reference the "rendered result" or "ROI Nodes" which have a "Numlist Node" in their ancestry which references the "rendered result". The latter case applies only if region is non-empty.
If non-empty, the function matches only "ROI Nodes" whose bounding box intersects with the supplied region. Note that this does not necessarily mean that any of the individual regions in the ROI description box will intersect with region, although it usually does mean this. See jpx_metanode::get_bounding_box for more on the bounding box.
Ignored unless region is a non-empty region. In this case, the function matches only "ROI Nodes" which contain at least one region, both of whose dimensions are no smaller than min_size.
This argument facilitates the efficient deployment of resolution sensitive metadata browsing systems. An interactive image browser, for example, may choose not to generate overlay information for spatially-sensitive metadata whose spatial dimensions are too small to be clearly discerned at the current viewing resolution. For example, streets might only become apparent on an image of a metropolitan area at some sufficiently fine level of image detail. Cluttering the image with metadata holding the street names before the streets can be clearly discerned would be inadvisable (and computationally inefficient).
| top || synopsis || return value || arguments || prev || next |