1Compression(3)        User Contributed Perl Documentation       Compression(3)
2
3
4

NAME

6       PDL::Compression - compression utilities
7

DESCRIPTION

9       These routines generally accept some data as a PDL and compress it into
10       a smaller PDL.  Algorithms typically work on a single dimension and
11       thread over other dimensions, producing a threaded table of compressed
12       values if more than one dimension is fed in.
13
14       The Rice algorithm, in particular, is designed to be identical to the
15       RICE_1 algorithm used in internal FITS-file compression (see
16       PDL::IO::FITS).
17

SYNOPSIS

19        use PDL::Compression
20
21        ($y,$xsize) = $x->rice_compress();
22        $c = $y->rice_expand($xsize);
23

FUNCTIONS

METHODS

26   rice_compress
27         Signature: (in(n); [o]out(m); int[o]len(); lbuf(n); int blocksize)
28
29       Squishes an input PDL along the 0 dimension by Rice compression.  In
30       scalar context, you get back only the compressed PDL; in list context,
31       you also get back ancillary information that is required to uncompress
32       the data with rice_uncompress.
33
34       Multidimensional data are threaded over - each row is compressed
35       separately, and the returned PDL is squished to the maximum compressed
36       size of any row.  If any of the streams could not be compressed (the
37       algorithm produced longer output), the corresponding length is set to
38       -1 and the row is treated as if it had length 0.
39
40       Rice compression only works on integer data types -- if you have
41       floating point data you must first quantize them.
42
43       The underlying algorithm is identical to the Rice compressor used in
44       CFITSIO (and is used by PDL::IO::FITS to load and save compressed FITS
45       images).
46
47       The optional blocksize indicates how many samples are to be compressed
48       as a unit; it defaults to 32.
49
50       How it works:
51
52       Rice compression is a subset of Golomb compression, and works on data
53       sets where variation between adjacent samples is typically small
54       compared to the dynamic range of each sample.  In this implementation
55       (originally written by Richard White and contributed to CFITSIO in
56       1999), the data are divided into blocks of samples (by default 32
57       samples per block).  Each block has a running difference applied, and
58       the difference is bit-folded to make it positive definite.  High order
59       bits of the difference stream are discarded, and replaced with a unary
60       representation; low order bits are preserved.  Unary representation is
61       very efficient for small numbers, but large jumps could give rise to
62       ludicrously large bins in a plain Golomb code; such large jumps ("high
63       entropy" samples) are simply recorded directly in the output stream.
64
65       Working on astronomical or solar image data, typical compression ratios
66       of 2-3 are achieved.
67
68         $out = $pdl->rice_compress($blocksize);
69         ($out, $len, $blocksize, $dim0) = $pdl->rice_compress;
70
71         $new = $out->rice_expand;
72
73       rice_compress ignores the bad-value flag of the input piddles.  It will
74       set the bad-value flag of all output piddles if the flag is set for any
75       of the input piddles.
76
77   rice_expand
78         Signature: (in(n); [o]out(m); lbuf(n); int blocksize)
79
80       Unsquishes a PDL that has been squished by rice_compress.
81
82            ($out, $len, $blocksize, $dim0) = $pdl->rice_compress;
83            $copy = $out->rice_expand($dim0, $blocksize);
84
85       rice_expand ignores the bad-value flag of the input piddles.  It will
86       set the bad-value flag of all output piddles if the flag is set for any
87       of the input piddles.
88

AUTHORS

90       Copyright (C) 2010 Craig DeForest.  All rights reserved. There is no
91       warranty. You are allowed to redistribute this software / documentation
92       under certain conditions. For details, see the file COPYING in the PDL
93       distribution. If this file is separated from the PDL distribution, the
94       copyright notice should be included in the file.
95
96       The Rice compression library is derived from the similar library in the
97       CFITSIO 3.24 release, and is licensed under yet more more lenient terms
98       than PDL itself; that notice is present in the file "ricecomp.c".
99

BUGS

101       •  Currently headers are ignored.
102
103       •  Currently there is only one compression algorithm.
104

TODO

106       •  Add object encapsulation
107
108       •  Add test suite
109
110
111
112perl v5.32.1                      2021-02-15                    Compression(3)
Impressum