.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Compression 3pm"
.TH Compression 3pm "2023-06-17" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDL::Compression \- compression utilities
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These routines generally accept some data as a \s-1PDL\s0 and compress it
into a smaller \s-1PDL.\s0  Algorithms typically work on a single dimension
and broadcast over other dimensions, producing a broadcasted table of
compressed values if more than one dimension is fed in.
.PP
The Rice algorithm, in particular, is designed to be identical to the
\&\s-1RICE_1\s0 algorithm used in internal FITS-file compression (see \s-1PDL::IO::FITS\s0).
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use PDL::Compression
\&
\& ($y,$xsize) = $x\->rice_compress();
\& $c = $y\->rice_expand($xsize);
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SH "METHODS"
.IX Header "METHODS"
.SS "rice_compress"
.IX Subsection "rice_compress"
.Vb 1
\&  Signature: (in(n); [o]out(m); int[o]len(); int blocksize)
.Ve
.PP
Squishes an input \s-1PDL\s0 along the 0 dimension by Rice compression.  In
scalar context, you get back only the compressed \s-1PDL\s0; in list context,
you also get back ancillary information that is required to uncompress
the data with rice_uncompress.
.PP
Multidimensional data are broadcasted over \- each row is compressed
separately, and the returned \s-1PDL\s0 is squished to the maximum compressed
size of any row.  If any of the streams could not be compressed (the
algorithm produced longer output), the corresponding length is set to \-1
and the row is treated as if it had length 0.
.PP
Rice compression only works on integer data types \*(-- if you have
floating point data you must first quantize them.
.PP
The underlying algorithm is identical to the Rice compressor used in
\&\s-1CFITSIO\s0 (and is used by \s-1PDL::IO::FITS\s0 to load and save compressed \s-1FITS\s0
images).
.PP
The optional blocksize indicates how many samples are to be compressed
as a unit; it defaults to 32.
.PP
How it works:
.PP
Rice compression is a subset of Golomb compression, and works on data sets
where variation between adjacent samples is typically small compared to the
dynamic range of each sample.  In this implementation (originally written
by Richard White and contributed to \s-1CFITSIO\s0 in 1999), the data are divided
into blocks of samples (by default 32 samples per block).  Each block 
has a running difference applied, and the difference is bit-folded to make
it positive definite.  High order bits of the difference stream are discarded,
and replaced with a unary representation; low order bits are preserved.  Unary
representation is very efficient for small numbers, but large jumps could
give rise to ludicrously large bins in a plain Golomb code; such large jumps
(\*(L"high entropy\*(R" samples) are simply recorded directly in the output stream.
.PP
Working on astronomical or solar image data, typical compression ratios of 
2\-3 are achieved.
.PP
.Vb 2
\&  $out = $pdl\->rice_compress($blocksize);
\&  ($out, $len, $blocksize, $dim0) = $pdl\->rice_compress;
\&
\&  $new = $out\->rice_expand;
.Ve
.PP
rice_compress ignores the bad-value flag of the input ndarrays.
It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
.SS "rice_expand"
.IX Subsection "rice_expand"
.Vb 1
\&  Signature: (in(n); [o]out(m); int blocksize)
.Ve
.PP
Unsquishes a \s-1PDL\s0 that has been squished by rice_compress.
.PP
.Vb 2
\&     ($out, $len, $blocksize, $dim0) = $pdl\->rice_compress;
\&     $copy = $out\->rice_expand($dim0, $blocksize);
.Ve
.PP
rice_expand ignores the bad-value flag of the input ndarrays.
It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
.SH "AUTHORS"
.IX Header "AUTHORS"
Copyright (C) 2010 Craig DeForest.
All rights reserved. There is no warranty. You are allowed
to redistribute this software / documentation under certain
conditions. For details, see the file \s-1COPYING\s0 in the \s-1PDL\s0
distribution. If this file is separated from the \s-1PDL\s0 distribution,
the copyright notice should be included in the file.
.PP
The Rice compression library is derived from the similar library in
the \s-1CFITSIO 3.24\s0 release, and is licensed under yet more more lenient
terms than \s-1PDL\s0 itself; that notice is present in the file \*(L"ricecomp.c\*(R".
.SH "BUGS"
.IX Header "BUGS"
.IP "\(bu" 3
Currently headers are ignored.
.IP "\(bu" 3
Currently there is only one compression algorithm.
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 3
Add object encapsulation
.IP "\(bu" 3
Add test suite