Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 354 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man1/pamtojpeg2k.1 b/upstream/mageia-cauldron/man1/pamtojpeg2k.1
new file mode 100644
index 00000000..e2d2bbe1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/pamtojpeg2k.1
@@ -0,0 +1,354 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamtojpeg2k User Manual" 0 "1 November 2022" "netpbm documentation"
+
+.SH NAME
+pamtojpeg2k - convert PAM/PNM image to a JPEG-2000 code stream
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamtojpeg2k\fP
+[\fB-imgareatlx=\fP\fIcolumn\fP]
+[\fB-imgareatly=\fP\fIrow\fP]
+[\fB-tilegrdtlx=\fP\fIcolumn\fP]
+[\fB-tilegrdtly=\fP\fIrow\fP]
+[\fB-tilewidth=\fP\fIcolumns\fP]
+[\fB-tileheight=\fP\fIrows\fP]
+[\fB-prcwidth=\fP\fIcolumns\fP]
+[\fB-prcheight=\fP\fIrows\fP]
+[\fB-cblkwidth=\fP\fIcolumns\fP]
+[\fB-cblkheight=\fP\fIrows\fP]
+[\fB-mode=\fP{\fBinteger\fP|\fBint\fP|\fBreal\fP}]
+[\fB-compression=\fP\fIratio\fP]
+[\fB-size=\fP\fIbytes\fP]
+[\fB-ilyrrates=\fP[\fIrealnumber\fP[,\fIrealnumber\fP, ...]]
+[\fB-numrlvls=\fP\fInumber\fP]
+[\fB-progression=\fP{\fBlrcp\fP|\fBrlcp\fP|\fBrpcl\fP|\fBpcrl\fP|\fBcprl\fP}]
+[\fB-numgbits=\fP\fInumber\fP]
+[\fB-nomct\fP]
+[\fB-sop\fP]
+[\fB-eph\fP]
+[\fB-lazy\fP]
+[\fB-termall\fP]
+[\fB-segsym\fP]
+[\fB-vcausal\fP]
+[\fB-pterm\fP]
+[\fB-resetprob\fP]
+[\fB-verbose\fP]
+[\fB-debuglevel=\fP\fInumber\fP]
+\fIfilename\fP
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpamtojpeg2k\fP converts the named PBM, PGM, PPM, or PAM file,
+or Standard Input if no file is named, to a JPEG-2000 code stream
+(JPC) file on Standard Output.
+.PP
+The JPEG-2000 specification specifies two separate formats: JP2
+and JPEG-2000 code stream (JPC).  JP2 represents a visual image quite
+specifically, whereas JPC is a more or less arbitrary array of codes.
+\fBpamtojpeg2k\fP can't produce a JP2, but the JPC image that
+\fBpamtojpeg2k\fP produces is very similar to a JP2 if the input is a
+PBM, PGM, or PPM image or equivalent PAM image.  One difference is
+that the RGB intensity values in a JP2 are SRGB values, while
+\fBpamtojpeg2k\fP produces ITU-R Recommendation BT.709 values.  Those
+are very similar, but not identical.  Another difference is that a JP2
+can contain extra information about an image that JPC cannot.
+.PP
+When the input is a PAM image other than a PBM, PGM, or PPM equivalent,
+the JPC raster produced contains whatever the PAM raster does.  It can have
+any number of planes with any meanings; the planes are in the same order in
+the JPC output as in the PAM input.
+.PP
+A JPC image has a "precision," which is the number of bits used for
+each code (in Netpbm lingo, "sample").  Actually, it has a separate
+precision for each component.  \fBpamtojpeg2k\fP uses for the
+precision of every component the least number of bits that can
+represent the maxval of the input image.  A JPC image does not have an
+independent concept of maxval; the maxval of a JPC sample is the
+maximum value that the number of bits specified by the precision can
+represent in pure binary code.  E.g. if the precision is 4, the maxval
+is 15.  \fBpamtojpeg2k\fP does of course scale the sample values from
+the input maxval to the output maxval.  Example: The input maxval is
+99.  This means JPC precision is 7 bits and the JPC maxval is 127.  A
+sample value of 33 in the input becomes a sample value of 43 in the
+output.
+.PP
+\fBpamtojpeg2k\fP generates the JPC output with the 
+.UR http://www.ece.uvic.ca/~mdadams/jasper/
+Jasper JPEG-2000 library
+.UE
+\&.  See documentation of the library for details on what
+\fBpamtojpeg2k\fP produces.  Note that the Jasper library contains
+facilities for reading PNM images, but \fBpamtojpeg2k\fP does not use
+those.  It uses the Netpbm library instead.  Note that the makers of
+the Jasper library write it "JasPer," but Netpbm documentation follows
+standard American English typography rules, which don't allow that
+kind of capitalization.
+.PP
+Use \fBjpeg2ktopam\fP to convert in the other direction.
+.PP
+The program \fBjasper\fP, which is packaged with the Jasper 
+JPEG-2000 library, also converts between JPEG-2000 and PNM formats.
+Because it's packaged with the library, it may exploit it better, 
+especially recently added features.  However, since it does not use the
+Netpbm library to read and write the Netpbm formats, it doesn't do as
+good a job on that side.
+.PP
+Another format with goals similar to those of JPEG-2000 but that allows for
+faster encoding and decoding, is
+JPEG-LS.  
+.UR http://charls.codeplex.com
+CharLS
+.UE
+\& is a package of
+software for using JPEG-LS.
+
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamtojpeg2k\fP recognizes the following
+command line options:
+
+.UN jasperopts
+.SS Jasper Library Options
+.PP
+These options are identical in name and function to options that the
+Jasper library JPC encoder subroutine takes.  See
+.UR http://www.ece.uvic.ca/~mdadams/jasper/
+Jasper documentation
+.UE
+\&
+for details.
+
+
+.TP
+\fB-imgareatlx=\fP\fIcolumn\fP
+.TP
+\fB-imgareatly=\fP\fIrow\fP
+.TP
+\fB-tilegrdtlx=\fP\fIcolumn\fP
+.TP
+\fB-tilegrdtly=\fP\fIrow\fP
+.TP
+\fB-tilewidth=\fP\fIcolumns\fP
+.TP
+\fB-tileheight=\fP\fIrows\fP
+.TP
+\fB-prcwidth=\fP\fIcolumns\fP
+.TP
+\fB-prcheight=\fP\fIrows\fP
+.TP
+\fB-cblkwidth=\fP\fIcolumns\fP
+.TP
+\fB-cblkheight=\fP\fIrows\fP
+.TP
+\fB-mode=\fP{\fBinteger\fP|\fBint\fP|\fBreal\fP}
+.TP
+\fB-ilyrrates=\fP[\fIrealnumber\fP[,\fIrealnumber\fP, ...]]
+.TP
+\fB-numrlvls=\fP\fInumber\fP
+.TP
+\fB-progression=\fP{\fBlrcp\fP|\fBrlcp\fP|\fBrpcl\fP|\fBpcrl\fP|\fBcprl\fP}
+.TP
+\fB-numgbits=\fP\fInumber\fP
+.TP
+\fB-nomct\fP
+.TP
+\fB-sop\fP
+.TP
+\fB-eph\fP
+.TP
+\fB-lazy\fP
+.TP
+\fB-termall\fP
+.TP
+\fB-segsym\fP
+.TP
+\fB-vcausal\fP
+.TP
+\fB-pterm\fP
+.TP
+\fB-resetprob\fP
+
+.PP
+\fB-ilyrrates\fP ('intermediate layer rates') lets you control
+  the compression at each layer.  The compressed image is arranged in layers,
+  so if you transmit it somewhere serially, enough information to make a low
+  quality image arrives soon, then later more information arrives to improve
+  the quality of the image, and so on until the entire image arrives.  The
+  value of this option is a list of ascending fractions, such as
+  '.1,.3,.5'.  Each fraction says the size of the layers up to and
+  including that layer should add up to that fraction of the size of the input
+  image.  If the size of the entire image is limited by \fB-compression\fP
+  or \fB-size\fP, none of these numbers may exceed that limit.
+
+.UN otheropts
+.SS Other Options
+
+
+
+.TP
+\fB-compression=\fP\fIratio\fP
+\fIratio\fP is a floating point number that specifies the compression
+ratio.  \fBpamtojpeg2k\fP will adjust quality as necessary to ensure that
+you get this compression ratio.  E.g. 4 means the output will be about
+one fourth the size in bytes of the input file.
+.sp
+The ratio concerns just the raster part of the image, with the denominator
+being what the raster would take if it were encoded the most naive way
+possible (e.g. 3 bytes per pixel in 8-bit-per-sample RGB).  It does,
+however, include metadata that is part of the compressed raster.  Because
+of that, it may not be possible to give you your requested compression ratio
+at any quality.  If it isn't, \fBpamtojpeg2k\fP fails with a message
+saying so.
+.sp
+If you don't specify this option, \fBpamtojpeg2k\fP gives you the best
+compression it can without losing any quality.  Because of the metadata issue
+described above, this may mean, for a small image, the image actually expands.
+.sp
+This option controls the 'rate' option of the Jasper library.
+Note that though the Jasper library takes a compression factor, this option
+specifies a compression ratio.  The compression factor is the multiplicative
+inverse of (1 divided by) the compression ratio.
+.sp
+You may not specify this with \fB-size\fP.
+.sp
+Before Netpbm 10.61 (December 2012), the default was a compression ratio
+of 1, and if \fBpamtojpeg2k\fP could not make the output that small, it just
+made it as small as it could, with zero quality.  You know this is happening
+when you see the warning message, "empty layer generated."
+
+.TP
+\fB-size=\fP\fIbytes\fP
+This option specifies the maximum size in bytes you want the output image
+to have.  This size is all-in, including headers and trailers and other
+metadata.  \fBpamtojpeg2k\fP will omit as much information as necessary to
+get under this limit.
+.sp
+It is possible to specify a value impossibly small, for example a value
+that doesn't even leave room for the image header.  If you do this, the
+program fails with an explanatory message.
+.sp
+This option controls the 'rate' option of the Jasper library.
+.sp
+You may not specify this with \fB-compression\fP.
+.sp
+This option was new in Netpbm 11.1 (December 2022).
+  
+  
+.TP
+\fB-verbose\fP
+This option causes \fBpamtojpeg2k\fP to issue informational messages about
+the conversion process.
+
+.TP
+\fB-debuglevel\fP=\fInumber\fP
+This option controls debug messages from the Jasper library.  
+\fBpamtojpeg2k\fP passes \fInumber\fP as the debug level to the Jasper
+JPC encoder.
+
+
+     
+.UN examples
+.SH EXAMPLES
+.PP
+This example compresses losslessly.
+
+.nf
+  pamtojpeg2k myimg.ppm >myimg.jpc
+
+.fi
+
+\fBjpeg2ktopam\fP will recreate myimg.ppm exactly.
+.PP
+This example compresses the file to one tenth its original size, throwing
+away information as necessary.
+
+.nf
+  pamtojpeg2k -compression=10 myimg.pgm >myimg.jpc
+
+.fi
+
+
+.UN jpeg2000
+.SH ABOUT JPEG-2000
+.PP
+JPEG-2000 is a format that compresses a visual image (or a similar set of
+data) into a minimal number of bytes for storage or transmission.  In that,
+its goal is similar to JPEG.  It has two main differences from JPEG.  
+.PP
+One difference is that it does a much better job on most images of
+throwing out information in order to achieve a smaller output.  That
+means when you reconstruct the image from the resulting compressed
+file, it looks a lot closer to the image you started with
+JPEG-2000 than with JPEG, for the same compressed file size.  Or, looked
+at another way, with JPEG-2000 you get a much smaller file than with 
+JPEG for the same image quality.
+.PP
+The second difference is that with JPEG-2000, you decide how much
+compression you want and the compressor adjusts the quality to meet your
+requirement, whereas with JPEG, you decide how much quality you want
+and the compressor adjusts the size of the output to meet your requirement.
+I.e. with JPEG-2000, the quality of the result depends on the compressibility
+of the input, but with JPEG, the \fIsize\fP of the result depends on
+the compressibility of the input.
+.PP
+With JPEG-2000, you can specify lossless compression, thus making it 
+compete with GIF and PNG.  With standard JPEG, you always lose something.
+(There are rumored to be variations of JPEG around that are lossless,
+though).
+.PP
+JPEG is much older than JPEG-2000 and far more popular.  JPEG is one of
+the half dozen most popular graphics formats and virtually all graphics
+facilities understand it.  JPEG-2000 is virtually unknown.
+.PP
+There is no compatibility between JPEG and JPEG-2000.  Programs that 
+read JPEG do not automatically read JPEG-2000 and vice versa.
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "jpeg2ktopam" (1)\c
+\&,
+.BR "pnmtojpeg" (1)\c
+\&,
+.BR "ppm" (1)\c
+\&,
+.BR "pgm" (1)\c
+\&,
+.BR "pbm" (1)\c
+\&,
+.BR "pam" (1)\c
+\&,
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamtojpeg2k\fP was added to Netpbm in Release 10.12 (November 2002).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamtojpeg2k.html
+.PP
\ No newline at end of file