CLI: 3D and 2D Compression and Decompression Utilities

CLI utility sperr3d performs compression and decompression tasks in 3D. Similarly, sperr2d operates on 2D data.

In compression mode, sperr3d (sperr2d) takes in a binary 3D volume (2D slice) in single- or double-precision floating point format, performs SPERR compression, and outputs the compact bitstream. It can also output the compressed and then decompressed data for evaluation purposes. Finally, it can print out compression quality measures (PSNR, L-Infty, and Accuracy Gain) for evaluation too.

In decompression mode, sperr3d (sperr2d) takes in a compressed bitstream, and outputs the decompressed data in single- or double-precision.

The best place to check out usage of this utility is its help message, i.e., the output of sperr3d -h:

3D SPERR compression and decompression

Usage: ./bin/sperr3d [OPTIONS] [filename]

Positionals:
  filename TEXT:FILE          A data volume to be compressed, or
                              a bitstream to be decompressed.

Options:
  -h,--help                   Print this help message and exit


Execution settings:
  -c Excludes: -d             Perform a compression task.
  -d Excludes: -c             Perform a decompression task.
  --omp UINT                  Number of OpenMP threads to use. Default (or 0) to use all.


Input properties (for compression):
  --ftype UINT                Specify the input float type in bits. Must be 32 or 64.
  --dims [UINT,UINT,UINT]     Dimensions of the input volume. E.g., `--dims 128 128 128`
                              (The fastest-varying dimension appears first.)


Output settings:
  --bitstream TEXT            Output compressed bitstream.
  --decomp_f TEXT             Output decompressed volume in f32 precision.
  --decomp_d TEXT             Output decompressed volume in f64 precision.
  --decomp_lowres_f TEXT      Output lower resolutions of the decompressed volume in f32 precision.
  --decomp_lowres_d TEXT      Output lower resolutions of the decompressed volume in f64 precision.
  --print_stats Needs: -c     Print statistics measuring the compression quality.


Compression settings:
  --chunks [UINT,UINT,UINT]   Dimensions of the preferred chunk size. Default: 256 256 256
                              (Volume dims don't need to be divisible by these chunk dims.)
  --pwe FLOAT Excludes: --psnr --bpp
                              Maximum point-wise error (PWE) tolerance.
  --psnr FLOAT Excludes: --pwe --bpp
                              Target PSNR to achieve.
  --bpp FLOAT:FLOAT in [0 - 64] Excludes: --pwe --psnr
                              Target bit-per-pixel (bpp) to achieve.

2D SPERR compression and decompression

Usage: ./bin/sperr2d [OPTIONS] [filename]

Positionals:
  filename TEXT:FILE          A data slice to be compressed, or
                              a bitstream to be decompressed.

Options:
  -h,--help                   Print this help message and exit


Execution settings:
  -c Excludes: -d             Perform a compression task.
  -d Excludes: -c             Perform a decompression task.


Input properties:
  --ftype UINT                Specify the input float type in bits. Must be 32 or 64.
  --dims [UINT,UINT]          Dimensions of the input slice. E.g., `--dims 128 128`
                              (The fastest-varying dimension appears first.)


Output settings:
  --bitstream TEXT            Output compressed bitstream.
  --decomp_f TEXT             Output decompressed slice in f32 precision.
  --decomp_d TEXT             Output decompressed slice in f64 precision.
  --decomp_lowres_f TEXT      Output lower resolutions of the decompressed slice in f32 precision.
  --decomp_lowres_d TEXT      Output lower resolutions of the decompressed slice in f64 precision.
  --print_stats Needs: -c     Show statistics measuring the compression quality.


Compression settings:
  --pwe FLOAT Excludes: --psnr --bpp
                              Maximum point-wise error (PWE) tolerance.
  --psnr FLOAT Excludes: --pwe --bpp
                              Target PSNR to achieve.
  --bpp FLOAT:FLOAT in [0 - 64] Excludes: --pwe --psnr
                              Target bit-per-pixel (bpp) to achieve.