kdu_params

This abstract base class must be derived to form a complete parameter class, such as siz_params, cod_params, etc. Each complete parameter class is intended primarily to represent the parameters embodied by a single type of code-stream marker segment; however, parameter classes may represent additional parameters which are not recorded in code-stream marker segments. In fact, it is possible to create parameter classes which are not associated with marker segments at all, but it is not possible to have code-stream marker segments whose parameters are managed by more than one parameter object.

We use the term attribute here to refer to a group of related parameter values within any given kdu_params-derived object. An attribute may have one value, a fixed number of values, or a variable length array of values, which describe some aspect of the coding system. For example, the width and height of an image together form a single attribute, its dimensions. The collection of mode switches (or flags) which control the behaviour of the JPEG2000 embedded block coder constitute another attribute, and so on. Attributes have identifying names which are useful when processing or generating text descriptors and also help to annotate the use of the generic access functions provided by the kdu_params base class.

The kdu_params base class provides several different mechanisms for importing and exporting parameter attribute values. Attributes may be recovered by parsing text strings (e.g., from a command-line or interactive prompt), by translating code-stream marker segments, or by explicit calls to a collection of overloaded set functions provided by the kdu_params base class. As an example, the following two mechanisms each set the number of DWT levels 7 in the main COD marker segment of an image whose coding parameters are headed by an object, root.

• root→parse_string("Clevels={7}");
• root→access_cluster(COD_prams)→set(Clevels,0,0,7);

As for internalization, parameter attributes may also be externalized in various ways: as human readable text (capable of being parsed back in); as valid JPEG2000 code-stream marker segments; or by direct query through a collection of overloaded get functons provided by the kdu_params base class.

Objects from each derived parameter class are collected into clusters, which manage related code-stream marker segments from different tiles and different image components. Specifically, the term cluster refers to all instances of any particular class derived from kdu_params which are involved in the description of a single compressed image, or its coding configuration. Within each cluster, the various instances of the relevant parameter class are identified by 3 coordinates: a tile index; a component index; and an instance index. Tile indices start from the special value of -1 (see below); component indices also start from a special value of -1; and instance indices start from 0. For some parameter classes (i.e., some types of clusters), multiple components, multiple tiles or multiple instances may be disallowed.

Although it is not necessary to know the details of the internal organization of parameter objects into clusters, it is helpful to understand this organization is based on a multi-dimensional list structure. Each cluster is organized firstly as a list of tiles. The first object in this list, the cluster head, does not refer to any one tile specifically, but provides coding parameters which are to be used in all tiles of the image, unless specifically overridden. The cluster head has the special tile index of -1. The other elements of the list have tile indices ranging from 0 to num_tiles-1; these indices are identical to those formally assigned to tiles by the JPEG2000 standard, running from left to right and top to bottom in raster-scan fashion. In this way, the total number of elements in the primary list of any given cluster is always num_tiles+1, allowing for the cluster head and one tile-specific object for each image tile. We refer to these num_tiles+1 objects as tile heads.

It is worth noting that specific parameter classes might not support tile-specific forms at all, in which case the primary list will consist only of the cluster head. The siz_params class has this restriction.

Branching off from each tile head is a secondary list of component-specific objects having component indices running from 0 to num_comps-1 where num_comps is the number of image components in the image, as defined by JPEG2000 (a colour image typically has 3 image components, one for each colour plane). The tile heads themselves all have component indices of -1. As for tiles, specific parameter classes may disable component-specific forms, in which case tile heads will not have any auxiliary list of component-specific objects. The siz_params and poc_params classes have this restriction.

Ignoring the possibility that tile- and/or component-specific forms might be prohibited by certain parameter classes, ror any given tile, t, of any given image component, c, there will be a corresponding object in the secondary list which has these tile and component indices. If this object does not provide specific values for some parameter attribute, the values default to those specified in the corresponding tile head (i.e., the object with tile index t and a component index of -1). If this object also fails to provide specific values for the relevant attribute, they are inherited from the object with component index c and a tile index of -1 (this is found in the auxiliary list whose tile head is the cluster head). If this also fails to produce results, the attribute is inherited from the cluster head itself.

As suggested by the above discussion, inheritance applies to entire attributes rather than specific values. If any values are available for some attribute in a particular parameter object, the entire attribute is considered to be specified for the purpose of the default inheritance procedure described above.

In most practical instances, most or all of the coding parameters will be identical in all tiles of all components (these are called tile-components in JPEG2000), meaning that most or all of the attributes will be specified only by the cluster head. Nevertheless, JPEG2000 allows tile-specific, component-specific and tile-component-specific overrides for many coding parameters and the inheritance rules described above are designed to mimic the philosophy underlying the JPEG2000 standard. It is worth noting that some parameter classes configure themselves (through calls to the protected define_attribute function) to explicitly disallow component-specific overrides of certain attributes, to reflect the capabilities offered by the JPEG2000 code-stream syntax.

According to the foregoing description, each cluster has a 2-dimensional list structure with ( num_components+1)*( num_tiles+1) elements, some or all of which may be permitted to hold distinct values for any particular attribute. Each of these elements is actually the head of a tertiary list of instances. The instance head has an instance index of 0 and any additional elements have consecutive, increasing instance indices with the same tile and component indices. Many parameter classes do not allow multiple instances. Instance lists are used to manage changes in parameter values from tile-part to tile-part. The poc_params class is an example of one which requires instance lists.

~kdu_params [virtual] {Java: Native_destroy}

link {Java: Link}

new_instance [virtual] {Java: New_instance}

copy_from {Java: Copy_from}

copy_all {Java: Copy_all}

identify_cluster {Java: Identify_cluster}

access_cluster (2 forms) {Java: Access_cluster}

get_instance {Java: Get_instance}

get_num_comps {Java: Get_num_comps}

access_relation {Java: Access_relation}

clear_marks {Java: Clear_marks}

any_changes {Java: Any_changes}

translate_marker_segment {Java: Translate_marker_segment}

generate_marker_segments {Java: Generate_marker_segments}

get (3 forms) {Java: Get}

compare (3 forms) {Java: Compare}

set (3 forms) {Java: Set}

set_derived {Java: Set_derived}

parse_string (2 forms) {Java: Parse_string}

textualize_attributes (2 forms) {Java: Textualize_attributes}

describe_attributes {Java: Describe_attributes}

describe_attribute {Java: Describe_attribute}

find_string

delete_unparsed_attribute {Java: Delete_unparsed_attribute}

finalize [virtual] {Java: Finalize}

finalize_all (2 forms) {Java: Finalize_all}