Custom Codec Settings

This page describes the custom codec settings available in Connect as per KAKADU's documentation.

1. Qstep

• Qstep[:<TC>]={<float>}

Base step size to be used in deriving irreversible quantization step sizes for every subband. The base step parameter should be in the 0 to 2 range. The default is 1/256.

2. fprec

• fprec <comp-0 precision>[L|M][,<comp-1 precision>[L|M][...]]

You can use this argument to adjust the way in which sample data precision is interpreted for the image components found in the input files. For files which have header information, the data is compressed as though the precision (bit-depth) were equal to the value(s) supplied here. This is most useful when the actual data occupies only a subset of the bits used to record information in the input image file(s). In this case, you would typically supply a smaller precision value for this argument, in order to provide a more suitable interpretation for the data being compressed and hence subsequent decompression and rendering.

For raw files, the precision of the original file data is still obtained from the Sprecision attribute (or Mprecision for Part 2 multi-component transforms), but the values of this attribute are changed to reflect the precision being forced. In either case, the generated codestream contains Sprecision (or Mprecision) attributes which reflect the forced precision values rather than those of the original sample data.

The argument takes a comma-separated list of non-negative precision values. The list can contain more values than the number of image components in the collection of input files. If it contains fewer values, the last value is replicated as required to provide forced precision values for all image components. You can supply the special value of 0 for any component (including the last one in the comma-separated list, which gets replicated). This special value means that the original precision should be left untouched.

Each value in the comma-separated list may optionally be followed by the single-character suffix of M or L:

• The M suffix means that the precision forcing algorithm should scale the data by a power of 2, so that the most significant bit in the original sample values aligns with the most significant bit of the representation produced by precision forcing. You would typically use this mode if you know that the least significant bits in a source file are guaranteed to be 0 and so there is no need to compress them -- particularly relevant for reversible (e.g., lossless) compression.
• The L suffix means that the precision forcing algorithm aligns least significant bits. This is also the default policy, in the event that no suffix is provided. In this case, there is no scaling, but values which exceed the range which can be represented using the forced precision must be clipped. You would typically use this mode if you know that some number of most significant bits in the original source samples are likely to be 0.

3. Sprofile

• Sprofile={ENUM<PROFILE0,PROFILE1,PROFILE2,PART2,CINEMA2K,CINEMA4K,BROADCAST>}

Restricted profile to which the code-stream conforms. The value must be an integer in the range 0 to 6, corresponding to the identifiers PROFILE0', PROFILE1', PROFILE2', PART2', CINEMA2K', CINEMA4K' and BROADCAST'.

• PROFILE0 is the most restrictive profile for Part 1 conforming codestreams.
• PROFILE2 places no restrictions on the code-stream other than those restrictions defined in ISO/IEC 15444-1 (JPEG2000, Part 1).
• A value of 3 (PART2') means that the codestream requires support for one or more features defined in ISO/IEC 15444-2 (JPEG2000, Part 2) -- additional information is provided via the Sextensions parameter attribute.
• Values 4 and 5 (CINEMA2K' and CINEMA4K') correspond to new profile restrictions for Digital Cinema.
• 6 (BROADCAST') identifies profile restrictions for broadcast applications.

The 2K and 4K digital cinema profiles and the broadcast profiles are closely related and very restrictive subsets of JPEG2000 Part 1, defined by various amendments to the original standard. If the system determines that support for Part 2 features is required, the profile will be set automatically to 3. Also, if the Sbroadcast attribute is present, the profile is automatically set to 6.

Otherwise, the profile is not adjusted by Kakadu's codestream creation machinery. However, if the profile is found to be insufficient, the system will generate a warning at the point where it first encounters an inconsistency. This might not occur until near the end of the processing in certain rare circumstances.

The system does perform some extensive checks for compliance with the Digital Cinema profiles when they are used, but only during codestream generation. It makes every effort to set default values in such a way as to ensure compliance with Digital Cinema profiles, where they are used, but it is ultimately up to the user to set the Creslengths attribute to ensure that compressed data sizes match the application-dependent constraints specified by the Digital Cinema amendment. Similar considerations apply to the broadcast profile, except it depends on additional information provided via the Sbroadcast parameter attribute (similar to the connection between the Part 2 profile and Sextensions). Defaults to Profile-2.

4. Sbroadcast

• Sbroadcast={<int>,ENUM<single,multi>,ENUM<irrev,rev>}

This parameter attribute provides more specific details for the BROADCAST profile (Sprofile'=6). Its 3 fields have the following interpretation:

1. The first field identifies the broadcast profile level, which is currently required to lie in the range 1 through 7. The profile level is concerned with the bit-rate and sampling rate of a compressed video stream, as described in Amendment 4 to IS15444-1. The system does not explicitly impose these constraints, since they depend upon the intended frame rate -- this can readily be done at the application level.
2. The second field indicates whether the single-tile (0) or multi-tile (1) variation of the profile is specified; the multi-tile variation allows for either 1 or 4 tiles per image, where multiple tiles must be identical in size and involve either 4 vertical tiles or 2 tiles in each direction.
3. The third field indicates whether the irreversible or reversible transform variation of the profile is specified. During codestream generation, this parameter attribute will default to the single-tile, irreversible level 1 variant if Sprofile' identifies the BROADCAST profile. Also, if Sbroadcast' is specified and Sprofile' is left unspecified, the system will automatically set `Sprofile' to 6 -- BROADCAST.

5. Cprecincts

• Cprecincts[:<TC>]={<int>,<int>},...

Precinct dimensions (must be powers of 2). Multiple records may be supplied, in which case the first record refers to the highest resolution level and subsequent records to lower resolution levels. The last specified record is used for any remaining lower resolution levels. Inside each record, vertical coordinates appear first.

6. ORGtparts

• ORGtparts[:<T>]={FLAGS<R|L|C>}

Controls the division of each tile's packets into tile-parts. The attribute consists of one or more of the flags, R', L' and C', separated by the vertical bar character, |'.

If the R' flag is supplied, tile-parts will be introduced as necessary to ensure that each tile-part consists of packets from only one resolution level.

If L' is supplied, tile-parts are introduced as necessary to ensure that each tile-part consists of packets from only one quality layer.

Similarly, if the `C' flag is supplied, each tile-part will consist of packets from only one component. Note that the cost of extra tile-part headers will not be taken into account during rate control, so that the code-stream may end up being a little larger than you expect.

By default, tile-part boundaries are introduced only as required by the presence of multiple Porder attribute specifications.

7. Corder

• Corder[:<T>]={ENUM<LRCP,RLCP,RPCL,PCRL,CPRL>}

Default progression order (may be overridden by Porder).

The four character identifiers have the following interpretation:

• L=layer; R=resolution; C=component; P=position.

The first character in the identifier refers to the index which progresses most slowly, while the last refers to the index which progresses most quickly. The default is LRCP.

8. ORGgen_plt

• ORGgen_plt[:<T>]={<yes/no>}

Requests the insertion of packet length information in the header of all tile-parts associated with tiles for which this attribute is turned on (has a value of "yes"). The PLT marker segments written into the relevant tile-part headers will hold the lengths of those packets which belong to the same tile-part. Note that the cost of any PLT marker segments generated as a result of this attribute being enabled will not be taken into account during rate allocation. This means that the resulting code-streams will generally be a little larger than one might expect. However, this is probably a reasonable policy, since the PLT marker segments may be removed without losing any information.

Also note that the ORGplt_parts attribute may be used to take control over the way in which PLT information is partitioned into distinct PLT marker segments.

9. ORGgen_tlm

• ORGgen_tlm[:<T>]={<int>}

Requests the insertion of TLM (tile-part-length) marker segments in the main header, to facilitate random access to the code-stream. This attribute takes a single integer-valued parameter, which identifies the maximum number of tile-parts that will be written to the code-stream for each tile.

The reason for including this parameter is that space for the TLM information must be reserved ahead of time. Once the entire code-stream has been written, the generation machinery goes back and overwrites this reserved space with actual TLM data. If the actual number of tile-parts which are generated is less than the value supplied here, empty tile-parts will be inserted into the code-stream so as to use up all of the reserved TLM space. For this reason, you should try to estimate the maximum number of tile-parts you will need as accurately as possible, noting that the actual value may be hard to determine ahead of time if incremental flushing features are to be employed. In any event, no JPEG2000 code-stream may have more than 255 tile-parts. An error will be generated at run-time if the declared maximum number of tile-parts turns out to be insufficient.

10. Creslengths

• Creslengths[:<TC>]={<int>},...

Maximum number of compressed bytes (packet headers plus packet bodies) that can be produced for each successive image resolution, starting from the highest resolution and working down to the lowest. The limit applies to the cumulative number of bytes generated for the resolution in question and all lower resolutions.

If the attribute is global to the entire codestream (no T or C specifier), the limit for each resolution applies to the cumulative number of bytes up to that resolution in all tiles and all image components.

If the attribute is tile-specific but not component-specific, the limit for each resolution applies to the cumulative number of bytes up to that resolution for all image components within the tile.

If the attribute is component-specific, the limit applies to the cumulative number of bytes up to the resolution in question across all tiles, but only in that image component.

Finally, if the attribute is component-specific and tile-specific, the limit applies to the cumulative number of bytes up to the resolution in question, within just that tile-component. You can provide limits of all four types. Moreover, you don't have to provide limits for all resolutions.

The initial set of byte limits applies only to the first quality layer to be generated during compression. Limits for additional quality layers may be supplied by inserting zero or negative values into the list; these are treated as layer delimiters. So, for example, the parameter string "1000,700,0,3000,2000,0,10000" provides limits of 1000 and 700 bytes for the highest and second highest resolutions in the first quality layer, 3000 and 2000 bytes for the same resolutions in the second quality layer, and a limit of 10000 bytes only to the highest resolution in the third quality layer. Any subsequent quality layers are not restricted by this parameter attribute.

11. Cblk

• Cblk[:<TC>]={<int>,<int>}

Nominal code-block dimensions (must be powers of 2, no less than 4 and no greater than 1024). Actual dimensions are subject to precinct, tile, and image dimensions. Vertical coordinates appear first. The default block dimensions are {64,64}.

12. Cycc

• Cycc[:<T>]={<yes/no>}

RGB to Luminance-Chrominance conversion? The default is to convert images with 3 or more components, unless a Part 2 multi-component transform is defined (Mcomponents > 0).

13. full

• -full

Forces encoding and storing of all bit-planes.

By default, the system incrementally constructs conservative estimates of the final rate allocation parameters and uses these to skip coding passes which are very likely to be discarded during rate allocation.

You might like to use the -full option if you are compressing an image with highly non-uniform statistics, so that rate prediction estimates that may truncate the amount of generated content are highly unreliable.

You might also like to use the -full option if you are using the -slope and -rate arguments together, in which case the -slope argument provides primary control over the generation of quality layers, subject to lower bounds on the quality layer bit-rates that are specified via -rate'. If you do not specify -full in such cases, the smallest distortion-length slope threshold supplied via the -slope argument.

14. rate

• -rate -|<bits/pel>,<bits/pel>,...

One or more bit-rates, expressed in terms of the ratio between the total number of compressed bits (including headers) and the product of the largest horizontal and vertical image component dimensions. A dash, "-", may be used in place of the first bit-rate in the list to indicate that the final quality layer should include all compressed bits.

Specifying a very large rate target is fundamentally different from using the dash, "-", because the former approach may cause the incremental rate allocator to discard terminal coding passes which do not lie on the rate-distortion convex hull. This means that reversible compression might not yield a truly lossless representation if you specify -rate without a dash for the first rate target, no matter how large the largest rate target is.

If Clayers is not used, the number of layers is set to the number of rates specified here. If "Clayers" is used to specify an actual number of quality layers, one of the following must be true: 1) the number of rates specified here is identical to the specified number of layers; or 2) one, two, or no rates are specified using this argument.

When two rates are specified, the number of layers must be 2 or more and intervening layers will be assigned roughly logarithmically spaced bit-rates.

When only one rate is specified, an internal heuristic determines a lower bound and logarithmically spaces the layer rates over the range.

If this argument is used together with -slope, and values supplied to -slope are non-zero (i.e., slope would also limit the amount of compressed data generated), the interpretation of the layer bit-rates supplied via this argument is altered such that they represent preferred lower bounds on the quality layer bit-rates. This will be taken into account in the event that the distortion-length slopes specified directly via the -slopes argument lead to the generation of too little content (i.e., if the source image turns out to be unexpectedly compressible).

15. slope

• -slope <layer slope>,<layer slope>,...

If present, this argument provides rate control information directly in terms of distortion-length slope values.

In most cases, you would not also supply the -rates argument. However, if you choose to do so, the values supplied via the -rates argument will be re-interpreted as lower bounds (as opposed to upper bounds) on the quality layer bit-rates, to be considered if the distortion-length slopes supplied here lead to unexpectedly small amounts of compressed data.

See the description of -rate for a more comprehensive explanation of the interaction between -rate and -slope. The remainder of this description, however, assumes that -slope is supplied all by itself.

If the number of quality layers is not specified via a Clayers argument, it will be deduced from the number of slope values. Slopes are inversely related to bit-rate, so the slopes should decrease from layer to layer. The program automatically sorts slopes into decreasing order so you need not worry about getting the order right. For reference we note that a slope value of 0 means that all compressed bits will be included by the end of the relevant layer, while a slope value of 65535 means that no compressed bits will be included in the layer.

The list of layer slope values must include at least one non-zero value. If fewer slopes are provided than the number of quality layers, there is an internal algorithm which either extrapolates or interpolates the values you have provided using a reasonable heuristic. Basically, the heuristic starts with the assumption that 256 is an excellent amount to separate successive layer slopes, since it represents roughly a sqrt(2) change in the bit-rate ignoring header overhead for most cases. The heuristic will not insert smaller slopes than the smallest one you supply, since that represents the maximum desired quality. If you supply two slopes, which are reasonably close together, the heuristic will reproduce the spacing you supply with these, but if interpolating the largest two supplied slopes leaves a gap closer to 256, that approach will be adopted.

16. precise

• -precise

Forces the use of 32-bit representations.
By default, 16-bit data representations will be employed for sample data processing operations (colour transform and DWT) whenever the image component bit-depth is sufficiently small.

17. no_weights

• no_weights Target MSE minimization for color images. By default, visual weights will be automatically used for color imagery (anything with 3 compatible components). Turn this off if you want direct minimization of the MSE over all reconstructed color components.

18. num_threads

• num_threads <#default threads>[,<#domain threads>[T|C]...]

Use this argument to gain explicit control over multi-threaded or single-threaded processing configurations. The special value of 0 may be used to specify that you want to use the conventional single-threaded processing machinery, meaning you don't want to create or use a threading environment.

Otherwise, you must supply a positive integer for the first argument, identifying the number of threads (including the main application thread) that have no preference as to where they do work. You also have the option to specify the number of additional threads that should be assigned a preference to doing sample data transform processing (T' suffix) or block coding operations (C' suffix). It is worth noting that -num_threads 1 and -num_threads 0 both result in single-threaded processing, although the former creates an explicit threading environment and uses it to schedule the processing steps, even if there is only one actual thread of execution.