Skip to content

Instantly share code, notes, and snippets.

@ahankinson

ahankinson/gist:4945722

Created February 13, 2013 16:17
Show Gist options
  • Save ahankinson/4945722 to your computer and use it in GitHub Desktop.
Save ahankinson/4945722 to your computer and use it in GitHub Desktop.
Download ZIP
kdu_compress options
Raw
gistfile1.txt
Usage:
"kdu_compress ...
-i <file 1>[*<copies>@<size>],... {see also `-fprec' & `-icrop'}
One or more input files. If multiple files are provided, they must be
separated by commas. Any spaces will be treated as part of the file
name. If any filename contains the optional "*<copies>@<size>" suffix,
that file actually contributes <copies> inputs, where the k'th copy
starts (k-1)*<size> bytes into the file; this is most useful for raw
files, allowing a single raw file to contribute multiple image
components.
Currently accepted image file formats are: TIFF (including BigTIFF),
RAW (big-endian), RAWL (little-endian), BMP, PBM, PGM and PPM, as
determined by the file suffix. For raw files, the sample bits must be
in the least significant bit positions of an 8, 16, 24 or 32 bit word,
depending on the bit-depth. Unused MSB's in each word are entirely
disregarded. The word organization is big-endian for files with the
suffix ".raw", but little-endian for files with the suffix ".rawl" -- be
careful to get this right. Also, with raw files, the dimensions,
precision and signed/unsigned characteristics must be provided
separately using `Sdims' (or any other appropriate combination of
SIZ-type parameters), `Sprecision' and `Ssigned'.
For non-raw files, the `S...' parameters are obtained from the file
header automatically. If there is a Part-2 multi-component transform,
however, the `Mcomponents', `Mprecision' and `Msigned' attributes are
set based on the file header, and you must generally supply suitable
values for `Scomponents', `Sprecision' and `Ssigned' along with the
multi-component transform specification. See the discussion and
examples which appear at the end of this usage statement for more on the
interaction between file header precision and dimensional information
with the configuration of coding parameter attributes.
There can be cases where you wish to compress the sample values found
in a file, using different precision properties to those which are
specified in the file header. This can be arranged via the `-fprec'
argument.
There are also cases where you wish to compress only a cropped
portion of an input file; this is particularly useful with the `-frag'
option. You can arrange for such cropping to take place via the
`-icrop' argument.
-o <compressed file -- raw code-stream, JP2 or JPX file>
Name of file to receive the compressed code-stream. If the file name
has a ".jp2" suffix (not case sensitive), the code-stream will be
wrapped up inside the JP2 file format. If the file name has a ".jpx" or
".jpf" suffix (not case sensitive), the code-stream will be wrapped up
inside the more sophisticated JPX file format, with a single compositing
layer. In either case, the first 3 source image components will be
treated as sRGB colour channels (red, green then blue) and the remainder
will be identified as auxiliary undefined components in the JP2/JPX
file, unless there are less than 3 colours, or a separate colour space
is identified via the `-jp2_space' and/or `-jpx_space' arguments.
If an input file defines a colour palette (quite common with BMP
files), this will be preserved through the JP2/JPX file format, and
samples will be correctly de-palettized by conformant JP2/JPX readers.
If there are fewer than 3 components available (taking any palette into
account), the first component will be identified as a luminance
component with the sRGB gamma and any remaining component will be
identified as an auxiliary undefined channel. Again, these default
decisions may be overridden by the `-jp2_space' and/or `-jpx_space'
arguments.
-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.
Note that it is up to the individual file format reading modules to
respect (or not) the information supplied via the `-fprec' argument. If
you have add your own file format support to this application, prior to
Kakadu version 6.1, this feature will probably not be supported.
-icrop {<off_y>,<off_x>,<height>,<width>},...
This argument provides a means to effectively crop the input files
supplied by `-i' -- essentially, the input file reading code limits its
access to just the cropped region and adjusts the dimensions reported
for the input file(s) accordingly. This option is especially useful
when combined with the fragmented compression option offered by `-frag'.
For example, you could invoke "kdu_compress" 40 times to compress a
200GB input file in 5GB fragments, each corresponding to large tile (for
example), simply by supplying the relevant tile indices to `-frag' and
the corresponding tile regions to `-icrop'. The argument takes one or
more sets of 4 cropping parameters, each of which is enclosed in curly
braces (remember to escape the braces in unix shells). The first set of
cropping parameters applies to the first file supplied via `-i'. The
second set of cropping parameters applies to the second input file, and
so forth, with the final set of cropping parameters applying to any
remaining input files. You should note that individual readers for each
file format may or may not support cropping -- if not supported you will
receive an appropriate error message. Certainly, cropping is supported
for at least some TIFF files.
-frag <tidx_y>,<tidx_x>,<thigh>,<twide>
Use this argument to compress only a fragment of the final codestream.
The four parameters identify the tiles which belong to the current
fragment. Specifically, <tidx_y> is the vertical tile index of the
first tile in the new fragment, measured relative to the first tile in
the image. That is, <tidx_y> is the number of tile rows above the
current fragment. Similarly, <tidx_x> is the number of tile columns to
the left of the fragment, while <thigh> and <twide> are the number of
tile rows and number of tile columns in the fragment. The first
fragment must have <tidx_x>=0 and <tidx_y>=0. The main codestream
header, plus any JP2/JPX header information will be written only in the
first fragment. The program leaves behind some additional information
in the output file, after a temporary EOC marker, which can be recovered
when the next fragment is compressed. This information identifies the
total number of tiles which have been compressed in all previous
fragments, and the total number of bytes associated with these previous
fragments. Together, this information is used to determine whether or
not this is the last fragment, and where any TLM information must be
written. If this argument is present, the dimensions of the entire
image must be explicitly identified via the `Sdims' attribute and/or the
`Ssize' and `Sorigin' attributes. Also, you must supply the tiling
attributes via `Stiles' and (optionally) `Stile_origin'. The input
image(s) supplied via `-i' describe only the fragment being compressed,
not the entire image. It is worth noting that TLM (tile-part-length)
marker segments can be requested by defining `ORGgen_tlm', and that this
funcionality works even when the image is being compressed in fragments.
Note finally, that the `-icrop' argument allows you to effectively crop
input files to just the fragment you are interested in compressing --
saves you having to split large input files up into fragments first.
-roi {<top>,<left>},{<height>,<width>} | <PGM image>,<threshold>
Establish a region of interest (foreground) to be coded more precisely
and/or earlier in the progression than the rest of the image
(background). This argument has no effect unless the "Rshift" attribute
is also set. The "Rlevels" attribute may also be used to control the
number of DWT levels which will be affected by the ROI information.
The single parameter supplied with this argument may take one of two
forms. The first form provides a simple rectangular region of interest,
specified in terms of its upper left hand corner coordinates
(comma-separated and enclosed in curly braces) and its dimensions (also
comma-separated and enclosed in braces). All coordinates and dimensions
are expressed relative to the origin and dimensions of the high
resolution grid (or canvas), using real numbers in the range 0 to 1. If
the original image is to be rotated during compression (see `-rotate'),
the coordinates supplied here are to be interpreted with respect to the
orientation of the image being compressed.
The second form for the single parameter string supplied with the
`-roi' argument involves a named (PGM) image file, separated by a comma
from an ensuing real-valued threshold in the range 0 to 1. In this
case, the image is scaled (interpolated) to fill the region occupied by
each image component. Pixel values whose relative amplitude exceeds the
threshold identify the foreground region.
-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 to 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 value 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 that 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). Note carefully, though, that the ability of the system
to respect any such lower bounds is limited by the number of bits
generated by block encoding, which may depend upon quantization
parameters as well as the use of slope thresholds during block encoding;
to avoid such limitations, you may wish to consider adjusting the
`Qstep' attribute and/or specifying the `-full' option.
-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.
-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 will be used to limit the amount of compressed data that is
actually generated during block encoding, which will limit (but not
nullify) the effectiveness of the lower rate bounds specified via
`-rate'.
-periodic_trimming yes|no -- override default policy
The system has the ability to discard compressed code-bytes which we
know we will not be needing on a regular basis, so as to conserve
memory. For large images, the memory consumption might become a
problem, especially if incremental flushing is not being used (see
`-flush_period'). On the other hand, periodically trimming the
compressed data that we know will ultimately not be written to the final
codestream can require substantial memory access overheads and may also
lock up an internal critical section for some time, which may
potentially affect multi-threaded processing efficiency. For these
reasons, the default policy is to enable periodic trimming only when
processing in the single-thread (corresponding to `-num_threads 0').
-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.
-tolerance <percent tolerance on layer sizes given using `-rate'>
This argument modifies the behaviour of the `-rate' argument slightly,
providing a tolerance specification on the achievement of the cumulative
layer bit-rates given by that argument. It has no effect if layer
construction is controlled using the `-slope' argument. The rate
allocation algorithm will attempt to find a distortion-length slope such
that the bit-rate, R_L, associated with layer L is in the range
T_L*(1-tolerance/100) <= R_L <= T_L, where T_L is the target bit-rate,
which is the difference between the cumulative bit-rate at layer L and
the cumulative bit-rate at layer L-1, as specified in the `-rate' list.
Note that the tolerance is given as a percentage, that it affects only
the lower bound, not the upper bound on the bit-rate, and that the
default tolerance is 0. If it is not possible to satisfy both bounds on
the layer bit-rate exactly, the layer will be assigned the largest size
which is consistent with the upper bound, if possible.
-flush_period <incremental flush period, measured in image lines>
By default, the system waits until all compressed data has been
generated, by applying colour transforms, wavelet transforms and block
encoding processes to the entire image, before any of this compressed
data is actually written to the output file. The present argument may
be used to request incremental flushing, where the compressed data is
periodically flushed to the output file, thereby avoiding the need for
internal buffering of the entire compressed image. The agument takes a
single parameter, identifying the minimum number of image lines which
should be processed before each attempt to flush new code-stream data.
The actual period may be larger, if insufficient data has been generated
to progress the code-stream.
Incremental flushing may be used with either `-slope' controlled
quality layers, or `-rate' driven quality layers; however, with
rate-driven quality layers you should be particularly careful to keep
the flushing period large enough to give the rate control algorithm a
decent amount of compressed data to perform effective rate control.
Generally a period of at least 1000 or 2000 image lines should be used
for rate driven flushing.
You should be aware of the fact that incremental flushing is possible
only on tile boundaries or when the packet progression sequence is
spatially progressive (PCRL), with sufficiently small precincts. The
vertical dimension of precincts in the lowest resolution levels must be
especially tightly controlled, particularly if you have a large number
of DWT levels. As an example, with `Clevels=6', the following precinct
dimensions would be a good choice for use with 32x32 code-blocks:
`Cprecincts={256,256},{128,128},{64,64},{32,64},{16,64},{8,64},{4,64}'.
-no_info -- prevents the inclusion of layer info in COM segments.
A code-stream COM (comment) marker segment is included in the main
header to record the distortion-length slope and the size of each
quality layer which is generated. If you wish to make the file as small
as possible and are working with small images, you may wish to disable
this feature by specifying the `-no_info' flag.
-com <comment string>
You can use this argument any number of times to include your own
comments directly in the codestream, as COM marker segments. Of course,
the supplied comment string must appear as a single command-line
argument, so you will need to quote any strings which contain spaces
when you supply this argument on the command line.
-no_weights -- target MSE minimization for colour images.
By default, visual weights will be automatically used for colour imagery
(anything with 3 compatible components). Turn this off if you want
direct minimization of the MSE over all reconstructed colour components.
-no_palette
This argument is meaningful only when reading palettized imagery and
compressing to a JP2/JPX file. By default, the palette will be
preserved in the JP2/JPX file and only the palette indices will be
compressed. In many cases, it may be more efficient to compress the RGB
data as a 24-bit continuous tone image. To make sure that this happens,
select the `-no_palette' option.
-jp2_space <sLUM|sRGB|sYCC|iccLUM|iccRGB>[,<parameters>]
You may use this to explicitly specify a JP2 compatible colour space
description to be included in a JP2/JPX file. If the colour space is
`sLUM' or `iccLUM', only one colour channel will be defined, even if the
codestream contains 3 or more components. The argument is illegal
except when the output file has the ".jp2", ".jpx" or ".jpf" suffix, as
explained above. Note that for JPX files (those having a ".jpx" or
".jpf" suffix), the `-jpx_space' argument may be supplied as an
alternative or in addition to this argument to provide richer colour
descriptions or even multiple colour descriptions. The pesent argument
must be followed by a single string consisting of one of 6 colour space
names, possibly followed by a comma-separated list of parameters.
If the space is "iccLUM", two parameters must follow, `gamma' and
`beta', which identify the tone reproduction curve. As examples, the
sRGB space has gamma=2.4 and beta=0.055, while NTSC RGB has gammma=2.2
and beta=0.099. A pure power law has beta=0, but is not recommended due
to the ill-conditioned nature of the resulting function around 0.
If the space is "iccRGB", 9 parameters must follow in the comma
separated list. The first two of these are the gamma and beta values,
as above. The next 2 parameters hold the X and Y chromaticity
coordinates of the first (typically red) primary colour. Similarly, the
next 4 parameters hold the X,Y coordinates of the second (typically
green) and third (typically blue) primary colour. The final parameter
must be one of the two strings "D50" or "D65", identifying the
illuminant. The present function assumes that equal amounts of all 3
primary colours produce the neutral (white) associated with this
illuminant.
-jpx_space <enumerated colour space>,[<prec>,<approx>]
This argument may be used only when writing JPX files (those with a
".jpx" or ".jpf" suffix). Although JPX files may contain arbitrary ICC
profiles, we do not provide the capability to include these from the
command line. Instead, we list here only the enumerated colour space
options defined by JPX. If `-jp2_space' is also supplied, multiple
colour descriptions will be written, with the JP2 compatible description
appearing first. If the `prec' and `approx' parameters are omitted from
the parameter list, they default to 0. Otherwise, the supplied
precedence must lie in the range -128 to +127 and the supplied
approximation level must lie in the range 0 to 4. The following
enumerated colour space names are recognized:
`bilevel1', `bilevel2', `YCbCr1', `YCbCr2', `YCbCr3', `PhotoYCC',
`CMY', `CMYK', `YCCK', `CIELab', `CIEJab', `sLUM', `sRGB', `sYCC',
`esRGB', `esYCC', `ROMMRGB', `YPbPr60', `YPbPr50'.
-jp2_aspect <aspect ratio of high-res canvas grid>
Identifies the aspect ratio to be used by a conformant JP2/JPX reader
when rendering the decompressed image to a display, printer or other
output device. The aspect ratio identifies ratio formed by dividing the
vertical grid spacing by the horizontal grid spacing, where the relevant
grid is that of the high resolution canvas. Sub-sampling factors
determine the number of high resolution canvas grid points occupied by
any given image component sample in each direction. By default
conformant JP2/JPX readers are expected to assume a 1:1 aspect ratio on
the high resolution canvas, so that the use of non-identical
sub-sampling factors for an image component implies a required aspect
ratio conversion after decompression.
-jp2_alpha -- treat 2'nd or 4'th image component as alpha
Use this argument if you want one of the image components to be treated
as an alpha channel for the pixels whose colour is represented by the
preceding components. If the colour space is grey-scale (see
`-jp2_space'), component 0 represents the intensity and component 1
represents alpha. More generally, if the colour space involves C colour
channels, the first C components represent these colour channels and the
next one represents alpha.
-jpx_layers [*|<num layers>]
This argument provides a simple mechanism for generating JPX files which
contain multiple compositing layers, each drawing their information from
a single codestream. A common application for this argument would be to
assign each image component (each slice) in a compressed medical volume
to a separate compositing layer. This allows efficient interactive
delivery of the compressed volume over JPIP, even where a
multi-component transform has been used to exploit redundancy between
components. To create richer JPX files, involving any number of
codestreams and the possibility of mixing components from different
codestreams in a single compositing layer, use the "kdu_merge" utility
to combine sources and redefine the layering, colour space and other
metadata. The present argument takes a single parameter, which either
specifies the number of layers L >= 1 to be generated, or specifies the
wildcard `*', which means that as many layers should be generated as
possible. The number of image components, C, used by each compositing
layer is determined by the colour space supplied to `-jp2_space' or
`-jpx_space', possibly supplemented by an alpha component if
`-jp2_alpha' is specified. In the absence of a supplied colour space,
the colour space is set to sLUM (if the number of components is less
than 3) or sRGB, for which C=1 and C=3, respectively. The created JPX
compositing layers consume components in order, C at a time, so that
there must be at least C*L image components available -- these are the
output image components produced at the output of any multi-component
transform during decompression (given by the `Mcomponents' attribute).
If the wildcard is given, the value of L is set as large as possible so
that C*L does not exceed the number of available components.
-jp2_box <file 1>[,<file 2>[,...]]
This argument provides a crude method for allowing extra boxes to be
inserted into a JP2 or JPX file. The extra boxes are written after the
main file header boxes, but before the contiguous code-stream box. The
argument takes a comma-separated list of file names, without any
intervening space. Each file represents a single top-level box, whose
box-type is found in the first 4 characters of the file, and whose
contents start immediately after the first new-line character and
continue until the end of the file. The first line of the file (the one
containing the box-type characters and preceding the box contents)
should not be more than 128 characters long. Each file may contain
arbitrary binary or ASCII data, but is always opened as binary.
-rotate <degrees>
Rotate source image prior to compression. Must be multiple of 90
degrees.
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, while 6 (`BROADCAST') identifies
profile restrictions for broadcast applications. The 2K and 4K digital
cinema profiles and the broadcast profiles are closely relatred and very
restrictive subsets ofJPEG2000 Part 1, defined by various ammendments 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 set automatically 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 comliance 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
ammendment.
Similar considerations apply to the broadcast profile, except that 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.]
Sextensions={FLAGS<DC|VARQ|TCQ|PRECQ|VIS|SSO|DECOMP|ANY_KNL|SYM_KNL|MCT|CURV
E|ROI>}
Logical OR of any combination of a number of flags, indicating extended
features from Part 2 of the JPEG2000 standard which may be found in this
codestream. Note that the Kakadu codestream generation machinery will
set these flags automatically based on features which are detected in
other parameter objects. Explanation: DC means arbitrary DC offset;
VARQ means variable quantization; TCQ means trellis-coded quantization;
PRECQ means precinct-dependent quantization; VIS means visual masking;
SSO means single-sample-overlap transform; DECOMP means arbitrary
decomposition styles; ANY_KNL means arbitrary transform kernels; SYM_KNL
means arbitrary whole sample symmetric transform kernels; MCT means
multi-component transform; CURVE means arbitrary point-transformation;
and ROI means extended region-of-interest signalling.
[Defaults to 0.]
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. 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 Ammendment 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. 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. 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.
Scap={<yes/no>}
Flag indicating whether or not capabilities defined in ammendments to
the standards, as recorded in the `CAP' marker segment, must be
recognized for correct decoding to occur. Currently, the only
recognized capabilities from ammendments are managed by the
`SCpart2_caps' attribute. You should not generally set this attribute
explicitly, but rely upon the default initialization procedure.
[Defaults to false unless a critical capability is found in
`SCpart2_caps'.]
SCpart2_caps={FLAGS<EXTENDED_COD>}
Logical OR of any combination of a number of flags, specifying the use
of extended capabilities from an ammendment to Part-2 (IS15444-2) of the
JPEG2000 family of standards. Currently, only one such capability,
EXTENDED_COD, is defined, corresponding to the possible presence of
block-coder extensions in COD/COC marker segments. This capability was
introduced with IS15444-2/AMD4.
[Defaults to 0.]
Ssize={<int>,<int>}
Canvas dimensions: vertical dimension first.
[For compressors, this will normally be derived from the dimensions
of the individual image components. Explicitly supplying the canvas
dimensions may be desirable if the source image files do not
indicate their dimensions, or if custom sub-sampling factors are
desired.]
Sorigin={<int>,<int>}
Image origin on canvas: vertical coordinate first.
[Defaults to {0,0}, or the tile origin if one is given]
Stiles={<int>,<int>}
Tile partition size: vertical dimension first.
[Defaults to {0,0}]
Stile_origin={<int>,<int>}
Tile origin on the canvas: vertical coordinate first.
[Defaults to {0,0}]
Scomponents={<int>}
Number of codestream image components.
[For compressors, this will normally be deduced from the number and
type of image files supplied to the compressor. Note carefully,
however, that if a multi-component transform is used, the number of
codestream image components might not be equal to the number of
`output image components' given by `Mcomponents'. In this case, the
value of `Mcomponents' and the corresponding `Mprecision' and
`Msigned' attributes should generally be associated with the image
files being read (for compression) or written (for decompression).]
Ssigned={<yes/no>},...
Indicates whether each codestream image component contains signed or
unsigned sample values.
[For compressors, this will normally be deduced from the image files
supplied to the compressor, but may be explicitly set if raw input
files are to be used. Also, if you happen to be using the Part-2
multi-component transform capabilities, the signed/unsigned
attributes of the original image components should be expressed by
`Msigned'; in this case, you will need to explicitly set `Ssigned'
in a manner which reflects the signed/unsigned characteristics of
the codestream image components produced after subjecting the
original components to the forward multi-component transform. Note
that the last supplied identifier is repeated indefinitely for all
remaining components.]
Sprecision={<int>},...
Indicates the bit-depth of each codestream image component.
[For compressors, this will normally be deduced from the image files
supplied to the compressor, but may need to be explicitly set if raw
input files are to be used. Also, if you happen to be using the
Part-2 multi-component transform capabilities, the precision of the
original image components should be expressed by `Mprecision'; in
this case, you will need to explicitly set `Sprecision' to reflect
the bit-depth of the codestream image components produced after
subjecting the original components to the forward multi-component
transform. Note that the last supplied value is repeated
indefinitely for all remaining components.]
Ssampling={<int>,<int>},...
Indicates the sub-sampling factors for each codestream image component.
In each record, the vertical factor appears first, followed by the
horizontal sub-sampling factor. The last supplied record is repeated
indefinitely for all remaining components.
[For compressors, a suitable set of sub-sampling factors will
normally be deduced from the individual image component dimensions.]
Sdims={<int>,<int>},...
Indicates the dimensions (vertical, then horizontal) of each individual
image component. The last supplied record is repeated indefinitely for
all remaining components.
[For compressors, the image component dimensions will normally be
deduced from the image files supplied to the compressor, but may be
explicitly set if raw input files are to be used.]
Mcomponents={<int>}
Number of image components produced at the output of the inverse
multi-component transform -- during compression, you may think of these
as original image comonents. In any event, we refer to them as "MCT
output components", taking the perspective of the decompressor. The
value of `Mcomponents' may be smaller than or larger than the
`Scomponents' value, which refers to the number of "codestream image
components". The codestream image components are supplied to the input
of the inverse multi-component transform. Note carefully, however, that
for Kakadu to perform a forward multi-component transform on image data
supplied to a compressor, the value of `Mcomponents' must be at least as
large as `Scomponents' and the inverse multi-component transform must
provide sufficient invertible transform blocks to derive the codestream
components from the output image components. In the special case where
`Mcomponents' is 0, or not specified, there is no multi-component
transform. In this case, `Scomponents', `Ssigned' and `Sprecision'
define the output image components. [Defaults to 0. You must
explicitly set a non-zero value for this attribute if you want to use
Part-2 multi-component transforms. Compressors might be able to deduce
this information from the input files, if they are aware that you want
to perform a multi-component transform.]
Msigned={<yes/no>},...
Indicates whether each MCT output component (see `Mcomponents' for a
definition of "MCT output components") contains signed or unsigned
sample values. If fewer than `Mcomponents' values are provided, the
last supplied identifier is repeated indefinitely for all remaining
components.
[Compressors might be able to deduce this information from the image
files supplied.]
Mprecision={<int>},...
Indicates the bit-depth of each MCT output component (see `Mcomponents'
for a definition of "MCT output components"). If fewer than
`Mcomponents' values are provided, the last supplied identifier is
repeated indefinitely for all remaining components.
[Compressors might be able to deduce this information from the image
files supplied.]
Cycc[:<T>]={<yes/no>}
RGB to Luminance-Chrominance conversion?
[Default is to convert images with 3 or more components, unless a
Part 2 multi-component transform is defined -- `Mcomponents' > 0]
Cmct[:<T>]={FLAGS<ARRAY|DWT>}
This parameter should be 0 unless a Part 2 multi-component transform is
being used, in which case it contains one or both of the `ARRAY' and
`DWT' options -- if both options are present, they are separated by a
`|'. The `ARRAY' option will be present if and only if an array-based
multi-component transform block is associated with the image, or the
relevant tile (for tile-specific instances of the attribute). The `DWT'
option will be present if and only if a DWT-based multi-component
transform block is associated with the image, or the relevant tile (for
tile-specific instances of the COD marker segment). Both flags will be
present if both types of multi-component transform block are employed
for the image or tile, as appropriate. During codestream generation,
the information in this parameter is generated automatically to conform
with the information provided via the `Mstages' and `Mstage_xforms'
attributes. When reading an existing codestream, the information in
this parameter should either be correct or 0. In the latter case, the
internal machinery interprets the codestream as one generated by
versions of Kakadu prior to v6.0, wherein the transform coefficients for
reversible matrix-based transforms were accidentally transposed -- the
transposition error is corrected automatically in this case.
Clayers[:<T>]={<int>}
Number of quality layers. May not exceed 16384.
[Default is 1]
Cuse_sop[:<T>]={<yes/no>}
Include SOP markers (i.e., resync markers)?
[Default is no SOP markers]
Cuse_eph[:<T>]={<yes/no>}
Include EPH markers (marker end of each packet header)?
[Default is no EPH markers]
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.
[Default is LRCP]
Calign_blk_last[:<T>]={<yes/no>,<yes/no>}
If "yes", the code-block partition is aligned so that the last sample in
each nominal block (ignoring the effect of boundaries) is aligned at a
multiple of the block dimension (a power of 2). Equivalently, the first
sample in each nominal block lies at a location which is a multiple of
the block dimension, plus 1. By default (i.e., "no"), the first sample
of each block is aligned at a multiple of the block dimension. The
alignment is specified separately for both dimensions, with the vertical
dimension specified first.
Clevels[:<TC>]={<int>}
Number of wavelet decomposition levels, or stages. May not exceed 32.
[Default is 5]
Cads[:<TC>]={<int>}
Index of the ADS marker segment used to hold Arbitrary Downsampling
Style information. If ADS information is involved, the value of the
`Cads' index must lie in the range 1 to 127. A value of 0 means that no
ADS marker segment is referenced. You will not normally set this
parameter yourself. It is preferable to allow the internal machinery to
find a suitable index. In any event, the ADS information recorded in
the `DOads' and `DSads' attributes will be generated automatically from
information contained in `Cdecomp'. During marker segment reading, the
ADS information is used together with any DFS information (see `Cdfs')
in order to reconstruct the `Cdecomp' attribute.
[Best not to set this yourself. An index is selected automatically
if `Cdecomp' defines a non-trivial decomposition.]
Cdfs[:<TC>]={<int>}
Index of the DFS marker segment used to hold Downsampling Factor Style
information. If DFS information is involved, the value of the `Cdfs'
index must be in the range 1 to 127. A value of 0 means that no DFS
marker segment is referenced. This attribute is ignored outside of the
main header (i.e., for non-negative tile indices). You will not
normally set this parameter yourself. Rather, it is preferable to allow
the internal machinery to find a suitable index for you. In any event,
the DFS instructions recorded in the `DSdfs' attribute will be generated
automatically from information contained in `Cdecomp'. During marker
segment reading, the DFS instructions will be read, along with any ADS
information (see `Cads') in order to reconstruct the `Cdecomp'
attribute.
[Best not to set this yourself. An index is selected automatically
if `Cdecomp' defines a non-trivial decomposition.]
Cdecomp[:<TC>]={<custom int>},...
Manages the information associated with the JPEG2000 Part-2 `ADS' and
`DFS' marker segments, if any, as referenced by the `Cads' and `Cdfs'
attributes. If neither of these is present, the default value of 3 is
used, which yields the conventional Mallat decomposition structure.
Each record describes the subband splitting processes for one entire DWT
level, starting from the first (highest frequency) level. The textual
form of each record commences with a primary splitting code, which is
one of the characters: `B' (split both ways a la Mallat); `H' (split
only horizontally); `V' (split only vertically); or `-' (do not split at
all -- degenerate case). The first option produces three primary detail
subbands, denoted HL, LH and HH. The second and third options produce
only one primary detail subband (HX or XH), while the last option
produces no detail subbands at all. The primary splitting code is
followed by parentheses, containing 0, 1 or 3 colon-separated
sub-strings, each of which describes the additional splitting operations
to be applied to each primary detail subband. Each sub-string consists
of 1, 3 or 5 characters, drawn from `-' (meaning no-split), `H' (meaning
a horizontal split), `V' (meaning a vertical split) and `B' (meaning a
bi-directional split). If the sub-string commences with `H' or `V', two
additional characters may be provided to describe further splitting of
the low- and high-pass subbands produced by the first split. If the
sub-string commences with `B', four additional characters may be
provided to describe further splitting of the LL, HL, LH and HH subbands
produced by the primary split. Alternatively, the sub-string may
consist only of the initial character, in which case no further
splitting is involved. Thus, "B" and "B----" are equivalent
sub-strings, as are "H" and "H--".
If insufficient parameters are supplied to accommodate the number of
desired DWT levels, the final value is simply replicated. Note,
however, that the last value must conform to some specific rules, which
derive from the way in which JPEG2000 Part-2 defines extrapolation for
information found in the ADS and DFS marker segments. In particular,
the terminal parameter must have identical splitting descriptors for all
primary detail subbands (remember there are 0, 1 or 3 of these).
Moreover, within each of these descriptors, all splitting codes (`-',
`H', 'V' and 'B') must be identical. The only exception to this occurs
where all primary detail subbands are split only once, in which case all
primary detail subbands must have identical sub-strings holding one of
the patterns, "B----", "H--", "V--" or "-". Thus, "B(-:-:-)",
"H(BBBBB)", "B(HHH:HHH:HHH)", "V(H--)" and "B(V--:V--:V--)" are all
legal terminal values, while "B(B:B:-)" and "V(VV-)" are not legal.
[If `Cdecomp' is not specified, a value is determined from the ADS
and/or DFS information referenced by `Cads' and `Cdfs'. If there is
no such information, the default `Cdecomp' value is "B(-,-,-)",
which translates to the integer value, 3. All Part-1 codestreams
must use this Mallat decomposition style.]
Creversible[:<TC>]={<yes/no>}
Reversible compression?
[Default is irreversible, if `Ckernels' and `Catk' are not used.
Otherwise, the reversibility is derived from those values.]
Ckernels[:<TC>]={ENUM<W9X7,W5X3,ATK>}
Wavelet kernels to use. The special value, `ATK' means that an ATK
(Arbitrary Transform Kernel) marker segment is used to store the DWT
kernel. In this case, the `Catk' attribute must be non-zero.
[Default is W5X3 if `Creversible' is true, W9X7 if `Creversible' is
false, and ATK if `Catk' is non-zero.]
Catk[:<TC>]={<int>}
A value of 0 means that the DWT kernel is one of W5X3 or W9X7, as
specified by the `Ckernels' attribute. Otherwise, this attribute holds
the index of the ATK marker segment which defines the transform kernel.
The index must lie in the range 2 to 255 and corresponding
`Kreversible', `Krev_steps' or `Kirv_steps' attributes must exist, which
have the same index (instance) value. Thus, for example, if `Catk=3',
you must also supply a value for `Kreversible:I3' and/or `Krev_steps:I3'
or `Kirv_steps:I3', as appropriate. This information allows the
internal machinery to deduce whether the transform is reversible or not.
The ATK information in these parameter attributes can also be
tile-specific.
[Default is 0]
Cuse_precincts[:<TC>]={<yes/no>}
Explicitly specify whether or not precinct dimensions are supplied.
[Default is "no" unless `Cprecincts' is used]
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.
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.
[Default block dimensions are {64,64}]
Cmodes[:<TC>]={FLAGS<BYPASS|RESET|RESTART|CAUSAL|ERTERM|SEGMARK|BYPASS_E1|BY
PASS_E2>}
Block coder mode switches. Any combination is legal. Note that the
`BYPASS_E2' and `BYPASS_E2' mode switches are specific to Part-2
codestreams that conform to the fast-mode defined in IS15444-2/AMD4.
These switches are meaningless unless combined with the `BYPASS' mode
switch, in which case the arithmetic coder is bypassed earlier than it
otherwise would be in the MR and SP coding passes by 2*`BYPASS_E2' +
1*`BYPASS_E1' bit-planes.
[By default, all mode switches are turned off]
Cweight[:<TC>]={<float>}
Multiplier for subband weighting factors (see `Clev_weights' and
`Cband_weights' below). Scaling all the weights by a single quantity
has no impact on their relative significance. However, you may supply a
separate weight for each component, or even each tile-component,
allowing you to control the relative signicance of image components or
tile-components in a simple manner.
Clev_weights[:<TC>]={<float>},...
Weighting factors for each successive resolution level, starting from
the highest resolution and working down to the lowest (but not including
the LL band!!). The last supplied weight is repeated as necessary.
Weight values are squared to obtain energy weights for weighted MSE
calculations. The LL subband always has a weight of 1.0, regardless of
the number of resolution levels. However, the weights associated with
all subbands, including the LL band, are multiplied by the value
supplied by `Cweight', which may be specialized to individual components
or tile-components.
Cband_weights[:<TC>]={<float>},...
Weighting factors for each successive subband, starting from the highest
frequency subbands and working down (i.e., HH1, LH1, HL1, HH2, ...). The
last supplied weight is repeated as necessary for all remaining subbands
(except the LL band). If `Clev_weights' is also supplied, both sets of
weighting factors are combined (multiplied). Weight values are squared
to obtain energy weights for weighted MSE calculations. The LL subband
always has a weight of 1.0, which avoids problems which may occur when
image components or tiles have different numbers of resolution levels.
To modify the relative weighting of components or tile-components,
including their LL subbands, use the `Cweight' option; its weighting
factors are multiplied by those specified using `Cband_weights' and
`Clev_weights'. If the `Cdecomp' attribute is used to describe more
general packet wavelet transforms, all subbands obtained by splitting an
HL, LH or HH subband will be assigned the same weight. No mechanism is
provided for specifying their weights separately. Moreover, all three
weights (HL, LH and HH) are present for each resolution level, even if
that level only involves horizontal or vertical splitting, and even in
the degenerate case of no splitting at all. For horizontal splitting
only, subbands derived from HX use the corresponding HL weight; HH and
LH weights are then ignored. Similarly for vertical splitting only,
subbands derived from XH use the corresponding LH weight; HH and HL
weights are then ignored.
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 need not 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.
Qguard[:<TC>]={<int>}
Number of guard bits to prevent overflow in the magnitude bit-plane
representation. Typical values are 1 or 2.
[Default is 1]
Qderived[:<TC>]={<yes/no>}
Quantization steps derived from LL band parameters? If "yes", all
quantization step sizes will be related to the LL subband's step sizes
through appropriate powers of 2 and only the LL band step size will be
written in code-stream markers. Otherwise, a separate step size will be
recorded for every subband. You cannot use this option with reversible
compression.
[Default is not derived]
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 range
0 to 2.
[Default is 1/256]
Qabs_steps[:<TC>]={<float>},...
Absolute quantization step sizes for each subband, expressed as a
fraction of the nominal dynamic range for that subband. The nominal
range is equal to 2^B (B is the image sample bit-depth) multiplied by
the DC gain of each low-pass subband analysis filter and the AC gain of
each high-pass subband analysis filter, involved in the construction of
the relevant subband. The bands are described one by one, in the
following sequence: LL_D, HL_D, LH_D, ..., HL_1, LH_1, HH_1. Here, D
denotes the number of DWT levels. Also, note that the actual set of
subbands for which values are provided depends upon the decomposition
structure identified via `Cdecomp'. A single step size must be supplied
for every subband (there is no extrapolation), except in the event that
`Qderived' is set to "yes" -- then, only one parameter is allowed,
corresponding to the LL_D subband.
[For compressors, the absolute step sizes are ignored if `Qstep' has
been used.]
Qabs_ranges[:<TC>]={<int>},...
Number of range bits used to code each subband during reversible
compression. Subbands appear in the sequence, LL_D, HL_D, LH_D, ...,
HL_1, LH_1, HH_1, where D denotes the number of DWT levels. Note that
the actual set of subbands for which values are provided depends upon
the decomposition structure, identified via `Cdecomp'. The number of
range bits for a reversibly compressed subband, plus the number of guard
bits (see `Qguard'), is equal to 1 plus the number of magnitude
bit-planes which are used for coding its samples.
[For compressors, most users will accept the default policy, which
sets the number of range bits to the smallest value which is
guaranteed to avoid overflow or underflow in the bit-plane
representation, assuming that the RCT (colour transform) is used.
If explicit values are supplied, they must be given for each and
every subband.]
Rshift[:<TC>]={<int>}
Region of interest up-shift value. All subband samples which are
involved in the synthesis of any image sample which belongs to the
foreground region of an ROI mask will be effectively shifted up (scaled
by two the power of this shift value) prior to quantization. The region
geometry is specified independently and is not explicitly signalled
through the code-stream; instead, this shift must be sufficiently large
to enable the decoder to separate the foreground and background on the
basis of the shifted sample amplitudes alone. You will receive an
appropriate error message if the shift value is too small.
[Default is 0]
Rlevels[:<TC>]={<int>}
Number of initial (highest frequency) DWT levels through which to
propagate geometric information concerning the foreground region for ROI
processing. Additional levels (i.e., lower frequency subbands) will be
treated as belonging entirely to the foreground region.
[Default is 4]
Rweight[:<TC>]={<float>}
Region of interest significance weight. Although this attribute may be
used together with `Rshift', it is common to use only one or the other.
All code-blocks whose samples contribute in any way to the
reconstruction of the foreground region of an ROI mask will have their
distortion metrics scaled by the square of the supplied weighting
factor, for the purpose of rate allocation. This renders such blocks
more important and assigns to them relatively more bits, in a manner
which is closely related to the effect of the `Clevel_weights' and
`Cband_weights' attributes on the importance of whole subbands. Note
that this region weighting strategy is most effective when working with
large images and relatively small code-blocks (or precincts).
[Default is 1, i.e., no extra weighting]
Porder[:<T>]={<int>,<int>,<int>,<int>,<int>,ENUM<LRCP,RLCP,RPCL,PCRL,CPRL>},
...
Progression order change information. The attribute may be applied
globally (main header), or in a tile-specific manner (tile-part header).
In this latter case, multiple instances of the attribute may be supplied
for any given tile, which will force the generation of multiple
tile-parts for the tile (one for each instance of the `Porder'
attribute). As with all attributes, tile specific forms are specified
by appending a suffix of the form ":T<tnum>" to the attribute name,
where <tnum> stands for the tile number, starting from 0. Each instance
of the attribute may contain one or more progression records, each of
which defines the order for a collection of packets. Each record
contains 6 fields. The first two fields identify inclusive lower bounds
for the resolution level and image component indices, respectively. The
next three fields identify exclusive upper bounds for the quality layer,
resolution level and image component indices, respectively. All indices
are zero-based, with resolution level 0 corresponding to the LL_D
subband. The final field in each record identifies the progression order
to be applied within the indicated bounds. This order is applied only to
those packets which have not already been sequenced by previous records
or instances.
CRGoffset={<float>,<float>},...
Provides additional component registration offsets. The offsets add to
those implied by the canvas coordinate system and should only be used
when canvas coordinates (notably `Ssize', `Soffset' and `Ssampling')
cannot be found, which adequately reflect the relative displacement of
the components. Each record specifies offsets for one component, with
the vertical offset appearing first. Offsets must be in the range 0
(inclusive) to 1 (exclusive) and represent a fraction of the relevant
component sub-sampling factor (see `Ssampling'). The last supplied
record is repeated as needed to recover offsets for all components.
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.]
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.
ORGplt_parts[:<T>]={FLAGS<R|L|C>}
Controls the division of packet length information into PLT marker
segments; this attribute has no impact unless `ORGgen_plt' is true. 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, new PLT marker segments will be started as required to ensure
that no PLT marker segment contains length information for packets that
belong to different resolution levels. Similarly, the `L' and `C' flags
cause packet length information to be partitioned into distinct PLT
marker segments at quality layer and codestream image component
boundaries, respectively.
[By default, packet length information is packed into the smallest
possible collection of PLT marker segments.]
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 which 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 generate 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. You should note that this
attribute may be ignored if the target device does not support
repositioning functionality.
ORGtlm_style[:<T>]={ENUM<implied,byte,short>,ENUM<short,long>}
This attribute can be used to control the format used to record TLM
(tile-part-length) marker segments; it is relevant only in conjunction
with "ORGgen_tlm". The standard defines 6 different formats for the TLM
marker segment, some of which are more compact than others. The main
reason for providing this level of control is that some
applications/profiles may expect a specific format to be used. By
default, each record in a TLM marker segment is written with 6 bytes, 2
of which identify the tile number, while the remaining 4 give the length
of the relevant tile-part. This attribute takes two fields: the first
field specifies the number of bytes to be used to record tile numbers
(0, 1 or 2); the second field specifies the number of bytes to be used
to record tile-part lengths (2 or 4). The values provided here might
not be checked ahead of time, which means that some combinations may be
found to be illegal at some point during the compression process. Also,
the first field may be 0 (meaning "implied") only if tiles are written
in order and have exactly one tile-part each. This is usually the case
if "ORGtparts" is not used, but incremental flushing of tiles which are
generated in an unusual order may violate this assumption -- this sort
of thing can happen if Kakadu's appearance transforms are used to
compress imagery which is presented in a transposed or flipped order,
for example.
Mmatrix_size[:<TI>]={<int>}
Identifies the number of matrix elements, if any, represented by this
object. The actual matrix coefficients are represented by the
`Mmatrix_coeffs' attribute. Matrices are used to describe reversible
and irreversible inverse component decorrelation transforms. This is
done by referencing the current attribute's instance index from the
second field in each record of the `Mstage_xforms' attribute used to
describe a multi-component transformation stage. Thus, for example,
"Mstage_xforms:I1={MATRIX,1,4,0,0},{MATRIX,3,0,1,0}" declares that a
given multi-component transform stage, having instance index 1, and two
component collections, employs matrix transforms for both collections.
The first collection's matrix is described by `Mmatrix_size:I1' and
`Mmatrix_coeffs:I1', while the second collection's matrix is described
by `Mmatrix_size:I3' and `Mmatrix_coeffs:I3'. To understand the last
two fields in each record of the `Mstage_xforms' attribute, please refer
to the separate description of that attribute.
Mmatrix_coeffs[:<TI>]={<float>},...
Coefficients of the matrix, if there is one, whose number of elements is
given by `Mmatrix_size'. The coefficients appear in row-major order
(first row, then second row, etc.). The height and width of the matrix
are not recorded here, but matrices are not required to be square. For
reversible transforms, the matrix coefficients are required to be
integers.
Mvector_size[:<TI>]={<int>}
Identifies the number of vector elements, if any, represented by this
object. The actual vector coefficients are represented by the
`Mvector_coeffs' attribute. Vectors are used to describe offsets to be
applied to the component sample values after inverse transformation.
This is done by referencing the current attribute's instance index from
the third field in each record of the `Mstage_xforms' attribute used to
describe a multi-component transform stage. Thus, for example,
"Mstage_xforms:I1={MATRIX,1,4,0,0},{MATRIX,3,0,1,0}" declares that a
given multi-component transform stage, having instance index 1, and two
component collections, employs matrix transforms for both collections.
The first collection also involves offsets, described via
`Mvector_size:I4' and `Mvector_coeffs:I4', while the second collection
does not use offsets. to understand the remaining fields in each record
of the `Mstage_xforms' attribute, consult the separate description of
that attribute.
Mvector_coeffs[:<TI>]={<float>},...
Coefficients of the vector, if there is one, whose number of elements is
given by `Mvector_size'. Unlike `Mmatrix_coeffs' and `Mtriang_coeffs',
this attribute is extrapolated if insufficient parameters are supplied
-- that is, the last supplied value is replicated as required in order
to provide all `Mvector_size' vector elements.
Mtriang_size[:<TI>]={<int>}
Identifies the total number of sub-triangular matrix elements, if any,
represented by this object. A sub-triangular matrix is square, with no
coefficients above the diagonal and at least one coefficient missing
from the diagonal. A strictly sub-triangular M x M matrix will have
M*(M-1)/2 coefficients, all below the diagonal. Matrices of this form
are used to describe irreversible multicomponent dependency transforms.
Reversible dependency transforms, however, include all but the upper
left diagonal entry, for a total of M*(M+1)/2-1 coefficients.
Dependency transforms are described by referencing the current
attribute's instance index from the second field in each record of the
`Mstage_xforms' attribute used to describe a multi-component transform
stage. Thus, for example, "Mstage_xforms:I1={DEP,5,0,0,0}" declares
that a given multi-component transform stage, having instance index 1,
and one component collection, employs a dependency transform, whose
coefficients are counted by `Mtriang_size:I5' and found in
`Mtriang_coeffs:I5'.
Mtriang_coeffs[:<TI>]={<float>},...
Coefficients of the sub-triangular matrix, if any, whose number of
elements is represented by the `Mtriang_size' attribute. The
coefficients are arranged in row-major order. Thus, for a dependency
transform with M inputs and outputs, the first coefficient (first two
for reversible transforms) comes from the second row of the matrix, the
next two (three for reversible transforms) comes from the third row of
the matrix, and so forth. For reversible transforms, the coefficients
must all have integer values.
Mstage_inputs[:<TI>]={<int>,<int>},...
This attribute is used to describe a list of input component indices
which are used by all transform blocks in a single stage of the
multi-component transform. This list of component indices is a
concatenation of the index ranges <A1>-<B1>, <A2>-<B2>, ..., where An <=
Bn are the first and second fields in the n'th record of the
`Mstage_inputs' attribute. The list of input component indices may
contain repeated values, but must cover all components produced by the
previous stage (or all codestream component indices, if this is the
first stage). In particular, it must always include 0. The first
transform block operates on the first N1 components identified by this
list; the second transform block operates on the next N2 components in
this list; and so forth.
Mstage_outputs[:<TI>]={<int>,<int>},...
This attribute is used to describe a list of output component indices
which are produced by this stage. This list of component indices is a
concatenation of the index ranges <A1>-<B1>, <A2>-<B2>, ..., where An <=
Bn are the first and second fields in the n'th record of the
`Mstage_outputs' attribute. The list of output component indices may
not contain any repeated component indices, but it may contain "holes".
The transform stage is considered to generate components with indices
from 0 to the largest index in the output list; any components in this
range which are not listed (these are the holes) are taken to be
identically equal to 0. The first transform block in the stage
processes the first N1 components in the list to produces the first M1
components in the output list; the second transform block in the stage
processes the next N1 components in the input list, producing the next
M2 components in the output list; and so forth.
Mstage_collections[:<TI>]={<int>,<int>},...
This attribute provides the values Nc and Mc which appear in the
descriptions of `Mstage_inputs' and `Mstage_outputs', for each transform
block (equivalently, each component collection), c. The `Mstage_blocks'
parameter attribute should contain one record for each transform. Each
record contains two strictly positive integers, identifying the number
of input components Nk, and the number of output components, Mk,
produced by the k'th transform. No transform may consume or produce 0
components. Between them, the various transform blocks must consume all
components in the input list described by `Mstage_inputs' and produce
all components in the output list described by `Mstage_outputs'.
Mstage_xforms[:<TI>]={ENUM<DEP,MATRIX,DWT,MAT>,<int>,<int>,<int>,<int>},...
This attribute provides one record for each transform block, which
describes the type of transform to be implemented in that block and the
parameters of the transform. The first field identifies the transform
as one of "dependency transform" (`DEP'), "decorrelation matrix
transform" (`MATRIX'), or "discrete wavelet transform" (`DWT'). Do not
use the `MAT' option; that option is provided to catch backward
compatibility problems with Kakadu versions prior to v6.0, in which
reversible decorrelation matrix transforms used a non-compliant
organization for the coefficient values. Kakadu will refuse to generate
codestreams which use the `MAT' option, although it should be able to
correctly recover and render codestreams generated with this option
prior to v6.0. It does this by recognizing the absence of the `Cmct'
parameter attribute (another oversight prior to v6.0) as an indication
that the non-compliant organization is being used.
The 2'nd field of each record holds the instance index of the
`Mtriang_coeffs' (for dependency transforms) or `Mmatrix_coeffs'
(for decorrelation matrix transforms) attributes, which provide the
actual transform coefficients, unless the transform is a DWT; in
this last case the 2'nd field holds 0 for the 9/7 DWT, 1 for the 5/3
DWT, or the instance index (in the range 2 to 255) of an `ATK'
marker segment whose `Kreversible', `Ksymmetric', `Kextension',
`Ksteps' and `Kcoeffs' attributes describe the DWT kernel. Apart
from DWT transforms, a 0 for this field means that the transform
block just passes its inputs through to its outputs (setting any
extra output components equal to 0) and adds any offsets specified
via the 3'rd field -- we refer to this as a "null" transform block.
The 3'rd field of each record holds the instance index of the
`Mvector_coeffs' attribute which describes any offsets to be applied
after inverse transformation of the input components to the block.
A value of 0 for this field means that there is no offset;
otherwise, the value must be in the range 1 to 255.
For DWT transforms, the 4'th field in the record identifies the
number of DWT levels to be used, in the range 0 to 32, while the
final field holds the transform origin, which plays the same role as
`Sorigin', but along the component axis. For dependency and
decorrelation transforms, the 4'th field must hold 0 if the
transform is irreversible, or 1 if it is reversible, while the 5'th
field must hold 0.
Mnum_stages[:<T>]={<int>}
Identifies the number of stages in the multi-component transform to be
applied to this tile, or (for main header attributes) as a default for
tiles which do not specify the `Mnum_stages' attribute. If this value
is 0, the spatially transformed codestream components associated with
the relevant tile are mapped directly to the output components specified
via the global `Mcomponents', `Msigned' and `Mprecision' attributes. If
`Mcomponents' is larger than `Scomponents', some final components are
automatically set to 0. Where the number of stages is 0, codestream
components which are identified as unsigned by the `Ssigned' attribute
are first offset (at least nominally) by half their dynamic range, in
the usual fashion. If, on the other hand, `Mnum_stages' specifies a
non-zero number of transform stages, component offsets must be provided
by the multi-component transform stages themselves.
It is worth noting that the above description applies to inverse
transformation (synthesis) during decompression. For a discussion
of the conditions under which an appropriate forward transform can
be performed during compression, see the description of the
`Mcomponents' attribute.
[This attribute defaults to 0 if a non-zero `Mcomponents' value
exists, indicating the presence of a multi-component transform.]
Mstages[:<T>]={<int>},...
Provides `Mnum_stages' records, each of which holds the instance index
(in the range 0 to 255) associated with the `Mstage_inputs',
`Mstage_outputs', `Mstage_blocks' and `Mstage_xforms' attributes which
describe the corresponding stage in the inverse multi-component
transform procedure. The last stage is the one which produces the final
decompressed components described by `Mcomponents', `Msigned' and
`Mprecision'.
Kreversible[:<TI>]={<yes/no>}
This attribute determines how the `Ksteps' and `Kcoeffs' attributes
should be treated. In the end, this parameter attribute must agree with
the value of the `Creversible' attribute, for any tile-component which
uses this transformation kernel. However this consistency may be
created by specifying `Kreversible' and leaving `Creversible'
unspecified, so that an appropriate default value will be selected.
[A default value cannot be created automatically, so you must
explicitly specify a value if you want ATK information to become
available for any particular instance index in the main header or a
tile header.]
Ksymmetric[:<TI>]={<yes/no>}
If true, the transform kernel belongs to the whole-sample symmetric
class, which is treated specially by JPEG2000 Part-2. The translated
impulse responses of these kernels are all symmetric about 0 -- see the
Taubman & Marcellin book, Chapter 6, for a definition of translated
impulse responses. Equivalently, all lifting steps involve even-length
symmetric lifting coefficients, Cs[n], where the coefficients associated
with steps s=0, 2, 4, ... are symmetric about n = 1/2 and the
coefficients associated with steps s=1, 3, 5, ... are symmetric about n
= -1/2.
[If you do not explicitly specify this attribute, it will be
determined automatically from the lifting coefficient values
supplied via `Krev_coeffs' or `Kirv_coeffs', as appropriate.]
Kextension[:<TI>]={ENUM<CON,SYM>}
Identifies the boundary extension method to be applied in each lifting
step. If `CON', boundary samples are simply replicated. The other
possible value, `SYM', means that boundary samples are symmetrically
extended. The centre of symmetry in this case is the boundary sample
location within an interleaved representation in which low-pass samples
occupy the even indexed locations and high-pass samples occupy the odd
indexed locations. The `SYM' method must be used if `Ksymmetric' is
true. Conversely, for filters which do not have the whole-sample
symmetric property, you are strongly recommended to use the `CON'
extension method.
[Defaults to `SYM' if the filters are whole-sample symmetric and
`CON' otherwise.]
Ksteps[:<TI>]={<int>,<int>,<int>,<int>},...
Array with one entry for each lifting step. The first entry corrsponds
to lifting step s=0, which updates odd indexed samples, based on even
indexed samples; the second entry corresponds to lifting step s=1, which
updates even indexed samples, based on odd indexed samples; and so
forth. The first field in each record holds the length, Ls, of the
coefficient array Cs[n], for the relevant step s. The second field is
the location of the first entry, Ns, where Cs[n] is defined for n=Ns to
Ns+Ls-1. The value of Ns is typically negative, but need not be. For
symmetric kernels, Ls must be even and Ns must satisfy
Ns=-floor((Ls+p-1)/2), where p is the lifting step parity (0 if s is
even, 1 if s is odd). The third and fourth fields must both be 0 if
`Kreversible' is false. For reversible transform kernels, however, the
third field holds the downshift value, Ds, while the fourth field holds
the rounding offset, Rs, to be added immediately prior to downshifting.
Kcoeffs[:<TI>]={<float>},...
Holds the lifting coefficients, Cs[n]. The first L0 records describe
the coefficients of the first lifting step. These are followed by the
L1 coefficients of the second lifting step, and so forth. The Ls values
are identified by the first field in each `Ksteps' record. Lifting step
s may be described by X_s[2k+1-p] += TRUNC(sum_{Ns<=n<Ns+Ls}
Cs[n]*X_{s-1}[2k+p+2n]). In the case of an irreversible transform, the
TRUNC operator does nothing and all arithmetic is performed (at least
notionally) in floating point. For reversible transforms, TRUNC(a) =
floor(a + Rs*2^{-Ds}) and Cs[n] is guaranteed to be an integer multiple
of 2^{-Ds}.
DSdfs[:<I>]={ENUM<X,H,V,B>},...
Describes the primary subband decomposition type associated with each
DWT level, starting from the highest resolution (1'st level). The value
may be one of `B' (split in both directions), `H' (split horizontally),
`V' (split vertically) or `X' (don't split at all). The last case is
degenerate, since it means that the DWT level in question produces no
detail subbands whatsoever, simply passing its input image through to
the next DWT level. However, this can be useful in some circumstances.
The primary subband decomposition determines the downsampling factors
between each successive resolution level. If there are more DWT levels
than `DSdfs' values, the last available value is replicated, as
required.
[You would not normally set values for this parameter attribute
yourself.]
Ddecomp[:<TI>]={<custom int>},...
This attribute is ultimately set so as to hold the same information as
the `Cdecomp' attribute of the COD/COC marker segment whose `Cads' holds
our instance index. Thus, for example, if `Cads'=3 then `Cdecomp' must
be identical to `Ddecomp:I3'. This identification is created by the
internal machinery, however. You should not explicitly set `Ddecomp'
values yourself.
DOads[:<TI>]={<int>},...
Number of sub-levels in each successive DWT level, starting from the
highest level. Accesses to non-existent values are supported by
repeating the last available value. All entries must lie in the range 1
to 3. For the meaning of sub-levels in JPEG2000 Part-2, the reader is
referred to Annex F of IS 15444-2.
[You would not normally set values for this parameter attribute
yourself.]
DSads[:<TI>]={ENUM<X,H,V,B>},...
Array of splitting instructions, whose interpretation generally depends
upon the way in which ADS and DFS tables are jointly referenced from
COD/COC marker segments, as identified by the `Cads' and `Cdfs'
attributes. Each splitting instruction must take one of the values: 3
(split horizontally and vertically); 2 (split vertically); 1 (split
horizontally); or 0 (do not split). The last value is repeated as
necessary, if accesses are made beyond the end of the array. For the
meaning of these splitting instructions, the reader is referred to Annex
F of IS 15444-2.
[You would not normally set values for this parameter attribute
yourself.]
-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 -- i.e., 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, and you have the option also 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.
For effective use of parallel processing resources, you should
consider creating at least one thread for each CPU; you should also
consider using the `-double_buffering' option to minimize the amount of
time threads might potentially sit idle. Assigning work domain
preferences to threads is an option that could be interesting to play
around with, since this might lead to better utilization of processor
caches.
If the `-num_threads' argument is not supplied explicitly, the
default behaviour is to create a threading environment only if the
system offers multiple CPU's (or virtual CPU's), with one thread per
CPU. However, this default behaviour depends upon knowledge of the
number of CPU's which are available -- something which cannot always be
accurately determined through system calls. The default value might
also not yield the best possible throughput.
-double_buffering <stripe height>
This option is intended to be used in conjunction with `-num_threads'.
From Kakadu version 7, double buffering is activated by default in
multi-threaded processing environments, but you can disable it by
supplying 0 to this argument.
Without double buffering, DWT operations are all performed by the
single thread which "owns" the multi-threaded processing group. For a
small number of processors, this may be acceptable, or even optimal,
since the DWT is generally quite a bit less CPU intensive than block
encoding (which is always spread across multiple threads, if available)
and synchronous single-threaded DWT operations may improve memory access
locality. However, even for a small number of threads, the amount of
thread idle time can be reduced by activating the `-double_buffering'
option. In this case, a certain number of image rows in each image
component are actually double buffered, so that one set can be processed
by colour transformation and sample reading operations, while the other
set is processed by the DWT analysis engines, which themselves drive the
block coding engines. The number of rows in each component which are to
be double buffered is known as the "stripe height", supplied as a
parameter to this argument. The stripe height can be as small as 1, but
this may add quite a bit of thread context switching overhead. For this
reason, a stripe height in the range 8 to 64 is recommended, while 32 is
selected by default in multi-threaded processing environments. If you
are working with small horizontal tiles, you may find that an even
larger stripe height is required for maximum throughput. In the extreme
case of very small tile widths and/or a very low number of threads, you
may find that the `-double_buffering' option hurts throughput. In any
case, the message is that for maximum throughput on a multi-processor
platform, you should be prepared to play with both the `-num_threads'
and `-double_buffering' options.
-progress <interval>
This option is useful when processing massive input images; it allows
you to receive feedback each time a vertical row of tiles has been
processed, but potentially more frequently, depending upon the
<interval> parameter. The application also provides feedback each time
codestream flushing is initiated (paricularly useful in conjunction with
`-flush_period'). The <interval> parameter indicates the maximum number
of lines that can be pushed into the compression machinery before some
progress is provided -- if this value is smaller than the tile height,
you will receive periodic information about the percentage of the
vertical row of tiles which has been processed.
-cpu <coder-iterations>
Times end-to-end execution and, optionally, the block encoding
operation, reporting throughput statistics. If `coder-iterations' is 0,
the block coder will not be timed, leading to the most accurate
end-to-end system execution times. Otherwise, `coder-iterations' must
be a positive integer -- larger values will result in more accurate
estimates of the block encoder processing time, but degrade the accuracy
of end-to-end system execution time estimates. Note that end-to-end
times include the impact of image file reading, which can be
considerable. Note also that timing information may not be at all
reliable unless `-num_threads' is 1. Since the default value for the
`-num_threads' argument may be greater than 1, you should explicitly set
the number of threads to 1 before collecting timing information.
-mem -- Report memory usage.
-s <switch file>
Switch to reading arguments from a file. In the file, argument strings
are separated by whitespace characters, including spaces, tabs and
new-line characters. Comments may be included by introducing a `#' or a
`%' character, either of which causes the remainder of the line to be
discarded. Any number of "-s" argument switch commands may be included
on the command line.
-record <file>
Record code-stream parameters in a file, using the same format which is
accepted when specifying the parameters on the command line.
-quiet -- suppress informative messages.
-version -- print core system version I was compiled against.
-v -- abbreviation of `-version'
-usage -- print a comprehensive usage statement.
-u -- print a brief usage statement."
Notes:
Arguments which commence with an upper case letter (rather than a dash)
are used to set up code-stream parameter attributes. These arguments have
the general form: <arg name>={fld1,fld2,...},{fld1,fld2,...},..., where
curly braces enclose records and each record is composed of fields. The
type and acceptable values for the fields are identified in the usage
statements, along with whether or not multiple records are allowed. In the
special case where only one field is defined per record, the curly braces
may be omitted. In no event may any spaces appear inside an attribute
argument.
Most of the code-stream parameter attributes take an optional
tile-component modifier, consisting of a colon, followed by a tile
specifier, a component specifier, or both. The tile specifier consists of
the letter `T', followed immediately be the tile index (tiles are numbered
in raster order, starting from 0). Similarly, the component specifier
consists of the letter `C', followed immediately by the component index
(starting from 0). These modifiers may be used to specify parameter changes
in specific tiles, components, or tile-components.
If you do not remember the exact form or description of one of the
code-stream attribute arguments, simply give the attribute name on the
command-line and the program will exit with a detailed description of the
attribute.
If SIZ parameters are to be supplied explicitly on the command line, be
aware that these may be affected by simultaneous specification of geometric
transformations. If uncertain of the behaviour, use `-record' to determine
the final compressed code-stream parameters which were used.
If you are compressing a 3 component image using the reversible or
irreversible colour transform (this is the default), the program will
automatically introduce a reasonable set of visual weighting factors, unless
you use the "Clev_weights" or "Cband_weights" options yourself. This does
not happen automatically in the case of single component images, which are
optimized purely for MSE by default. To see whether weighting factors were
used, you may like to use the `-record' option.
Understanding Multi-Component Transforms:
From version 4.6, Kakadu supports JPEG2000 Part 2 multi-component
transforms. These features are used if you define the `Mcomponents'
attribute to be anything other than 0. In this case, `Mcomponents' denotes
the number of multi-component transformed output components produced during
decompression, with `Mprecision' and `Msigned' identifying the precision and
signed/unsigned attributes of these components. These parameters will be
derived from the source files (non-raw files), or else they will be used to
figure out the source file format (raw files). When working with
multi-component transforms, the term "codestream components" refers to the
set of components which are subjected to spatial wavelet transformation,
quantization and coding. These are the components which are supplied to the
input of the multi-component transform during decompression. The number of
codestream components is given by the `Scomponents' attribute, while their
precision and signed/unsigned properties are given by `Sprecision' and
`Ssigned'. You should set these parameter attributes to suitable values
yourself. If you do not explicitly supply a value for the `Scomponents'
attribute, it will default to the number of source components (image planes)
found in the set of supplied input files. The value of `Mcomponents' may
also be larger than the number of source components found in the supplied
input files. In this case, the source files provide the initial set of
image components which will be recovered during decompression. This subset
must be larger enough to allow the internal machinery to invert the
multi-component transform network, so as to recover a full set of codestream
image components. If not, you will receive a descriptive error message
explaining what is lacking.
As an example, suppose the codestream image components correspond to the
first N <= M principle components of an original set of M image components
-- obtained by applying the KLT to, say, a hyperspectral data set. To
compress the image, you would probably want to supply all M original image
planes. However, you could supply as few as the first N original image
planes. Here, M is the value of `Mcomponents' and N is the value of
`Scomponents'.
If there is no multi-component transform, `Scomponents' is the number of
output and codestream components; it will be set to the number of source
components found in the set of supplied input files. `Sprecision' and
`Ssigned' hold the bit-depth and signed/unsigned attributes of the image
components. For raw files, these must be supplied explicitly on the command
line; otherwise, they are derived from the input file headers.
It is worth noting that the dimensions of the N=`Scomponents' codestream
image components are assumed to be identical to those of the N source image
components contained in the set of supplied input files. This assumption is
imposed for simplicity in this demonstration application; it is not required
by the Kakadu core system.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment