# General interface

The ATC compression and decompression functions can be split into three categories, each with their own task:

- `compress`: Compression

- `decompress`: Decompression

- `compress_decompress`: Compression followed by immediate decompression of the dataset. These functions can provide extra functionality over a `compress` call followed by a decompress call because they allow the user to request error calculation using the option `calculate_error`, i.e. the exact decompression error will be calculated and returned. To achieve this, the original data is only loaded once and is kept in memory for comparison later. Although this decreases IO in case the original data was stored in a file, this also increases peak memory usage, so depending on the user’s needs `compress_decompress` may or may not be the right function to call.

Furthermore, the original, compressed and decompressed data can be passed in/out in three different ways:

- As a file, by providing a path (`std::string`)

- As a buffer in-memory, by passing the buffer size (`size_t`) and a pointer to the first element (`dtype*` in the case of original/decompressed data, `char*` in the case of compressed data). ATC will never read or write past the given buffer size.

- As a buffer in-memory, by passing a vector (`std::vector<dtype>` in the case of original/decompressed data, `std::vector<char>` in the case of compressed data). When returning data using vectors, this is done using the `atc::Results` and `atc::TypedResults` structs.

Because of all these combinations, there are a lot of “instantiations” of `compress`, `decompress` and `compress_decompress`, although they only differ in terms of the data interface they provide. Therefore, we will only provide some documentation for each group as a whole. Note that each of these calls takes an optional `atc::Options` argument, which is covered on the Options page. Also, there are no functions which output compressed data into a user-provided pointer (the second case in the aforementioned list), because the user cannot determine the appropriate buffer size beforehand.

As for the return values of these functions, we refer to the Results page. Moreover, most ATC calls can throw exceptions, mostly because of invalid arguments. Since their error messages should already be descriptive enough on their own, these are not documented here.

Finally, ATC also provides some utility functions, which are documented at the end of this page.

## atc::compress

Apart from the original/compressed data and options arguments, which were covered at the start of this page, `compress` functions take the following arguments:

- `atc::DataType` data_type: Only necessary when passing the original data as a file. Because the original data is not passed as a typed buffer, ATC needs to be explicitly told about the data type of the original data.

- `std::vector<size_t>` sizes: The mode sizes of the original data tensor.

- `double` target_error: The target error, represented in the error metric stored in the option `error_metric` (default: PSNR, i.e. peak signal-to-noise ratio).

Note that when there is no `compressed_file` argument specified, this indicates the compressed output is being returned using as an `std::vector<char>` using the field `compressed_data` inside `atc::Results`.

Results compress(const std::string &original_file, DataType data_type, const std::vector<size_t> &sizes, double target_error, const std::string &compressed_file, const Options &options = Options())

Results compress(const std::string &original_file, DataType data_type, const std::vector<size_t> &sizes, double target_error, const Options &options = Options())

template<typename dtype>
Results compress(const dtype *original_data, const std::vector<size_t> &sizes, double target_error, const std::string &compressed_file, const Options &options = Options())

template<typename dtype>
Results compress(const dtype *original_data, const std::vector<size_t> &sizes, double target_error, const Options &options = Options())

template<typename dtype>
Results compress(const std::vector<dtype> &original_data, const std::vector<size_t> &sizes, double target_error, const std::string &compressed_file, const Options &options = Options())

template<typename dtype>
Results compress(const std::vector<dtype> &original_data, const std::vector<size_t> &sizes, double target_error, const Options &options = Options())

## atc::decompress

Apart from the compressed/decompressed data and options arguments, which were covered at the start of this page, `decompress` functions do not take any arguments, since all metadata is already stored in the compressed data. Note that when there is no `decompressed_file` or `decompressed_data` argument specified, this indicates the decompressed output is being returned using as an `std::vector<dtype>` using the field `decompressed_data` inside `atc::TypedResults`.

Results decompress(const std::string &compressed_file, const std::string &decompressed_file, const Options &options = Options())

template<typename dtype>
Results decompress(const std::string &compressed_file, size_t decompressed_size, dtype *decompressed_data, const Options &options = Options())

template<typename dtype>
TypedResults<dtype> decompress(const std::string &compressed_file, const Options &options = Options())

Results decompress(size_t compressed_size, const char *compressed_data, const std::string &decompressed_file, const Options &options = Options())

template<typename dtype>
Results decompress(size_t compressed_size, const char *compressed_data, size_t decompressed_size, dtype *decompressed_data, const Options &options = Options())

template<typename dtype>
TypedResults<dtype> decompress(size_t compressed_size, const char *compressed_data, const Options &options = Options())

Results decompress(const std::vector<char> &compressed_data, const std::string &decompressed_file, const Options &options = Options())

template<typename dtype>
Results decompress(const std::vector<char> &compressed_data, size_t decompressed_size, dtype *decompressed_data, const Options &options = Options())

template<typename dtype>
TypedResults<dtype> decompress(const std::vector<char> &compressed_data, const Options &options = Options())

## atc::compress_decompress

In terms of the interface, the `compress_decompress` functions are simply a combination of the aforementioned `compress` and `decompress` functions described. Therefore, we do not provide specific documentation for this group.

Results compress_decompress(const std::string &original_file, DataType data_type, const std::vector<size_t> &sizes, double target_error, const std::string &compressed_file, const std::string &decompressed_file, const Options &options = Options())

template<typename dtype>
Results compress_decompress(const std::string &original_file, const std::vector<size_t> &sizes, double target_error, const std::string &compressed_file, dtype *decompressed_data, const Options &options = Options())

template<typename dtype>
TypedResults<dtype> compress_decompress(const std::string &original_file, const std::vector<size_t> &sizes, double target_error, const std::string &compressed_file, const Options &options = Options())

Results compress_decompress(const std::string &original_file, DataType data_type, const std::vector<size_t> &sizes, double target_error, const std::string &decompressed_file, const Options &options = Options())

template<typename dtype>
Results compress_decompress(const std::string &original_file, const std::vector<size_t> &sizes, double target_error, dtype *decompressed_data, const Options &options = Options())

template<typename dtype>
TypedResults<dtype> compress_decompress(const std::string &original_file, const std::vector<size_t> &sizes, double target_error, const Options &options = Options())

template<typename dtype>
Results compress_decompress(const dtype *original_data, const std::vector<size_t> &sizes, double target_error, const std::string &compressed_file, const std::string &decompressed_file, const Options &options = Options())

template<typename dtype>
Results compress_decompress(const dtype *original_data, const std::vector<size_t> &sizes, double target_error, const std::string &compressed_file, dtype *decompressed_data, const Options &options = Options())

template<typename dtype>
TypedResults<dtype> compress_decompress_to_memory(const dtype *original_data, const std::vector<size_t> &sizes, double target_error, const std::string &compressed_file, const Options &options = Options())

  This function name is more verbose in order to disambiguate it from the next function, which happens to have the same argument types and only differs in its return type.

template<typename dtype>
Results compress_decompress(const dtype *original_data, const std::vector<size_t> &sizes, double target_error, const std::string &decompressed_file, const Options &options = Options())

template<typename dtype>
Results compress_decompress(const dtype *original_data, const std::vector<size_t> &sizes, double target_error, dtype *decompressed_data, const Options &options = Options())

template<typename dtype>
TypedResults<dtype> compress_decompress(const dtype *original_data, const std::vector<size_t> &sizes, double target_error, const Options &options = Options())

template<typename dtype>
Results compress_decompress(const std::vector<dtype> &original_data, const std::vector<size_t> &sizes, double target_error, const std::string &compressed_file, const std::string &decompressed_file, const Options &options = Options())

template<typename dtype>
Results compress_decompress(const std::vector<dtype> &original_data, const std::vector<size_t> &sizes, double target_error, const std::string &compressed_file, dtype *decompressed_data, const Options &options = Options())

template<typename dtype>
TypedResults<dtype> compress_decompress_to_memory(const std::vector<dtype> &original_data, const std::vector<size_t> &sizes, double target_error, const std::string &compressed_file, const Options &options = Options())

  This function name is more verbose in order to disambiguate it from the next function, which happens to have the same argument types and only differs in its return type.

template<typename dtype>
Results compress_decompress(const std::vector<dtype> &original_data, const std::vector<size_t> &sizes, double target_error, const std::string &decompressed_file, const Options &options = Options())

template<typename dtype>
Results compress_decompress(const std::vector<dtype> &original_data, const std::vector<size_t> &sizes, double target_error, dtype *decompressed_data, const Options &options = Options())

template<typename dtype>
TypedResults<dtype> compress_decompress(const std::vector<dtype> &original_data, const std::vector<size_t> &sizes, double target_error, const Options &options = Options())

## atc::read_data_type

The following functions determine the original data type of a compressed output object. This can be useful when decompressing into memory so a buffer of the appropriate type can be pre-allocated.

DataType read_data_type(const std::string &compressed_file)

  Determines the data type of the data represented by a compressed file.

DataType read_data_type(size_t compressed_size, const char *compressed_data)

  Determines the data type of the data represented by a compressed output buffer of a given length.

DataType read_data_type(const std::vector<char> &compressed_data)

  Determines the data type of the data represented by a compressed output buffer stored as an `std::vector<char>`.

## atc::read_decompressed_size

The following functions determine the size (i.e. the number of elements) of the decompressed output if the given compressed output object were to be decompressed with the given decompression options, specifically depending on the given cut-out. This can be useful when decompressing into memory so a buffer of the appropriate size can be pre-allocated. Note that when autocrop is enabled, we cannot exactly predict the final decompressed size so we assume nothing is cropped and return a safe upper bound.

size_t read_decompressed_size(const std::string &compressed_file, const Options &options = Options())

  Determines the number of elements in the decompressed output from a compressed file.

size_t read_decompressed_size(size_t compressed_size, const char *compressed_data, const Options &options = Options())

  Determines the number of elements in the decompressed output from a compressed output buffer of a given length.

size_t read_decompressed_size(const std::vector<char> &compressed_data, const Options &options = Options())

  Determines the number of elements in the decompressed output from a compressed output buffer stored as an `std::vector<char>`.

## atc::calculate_decompressed_size

size_t calculate_decompressed_size(const std::vector<size_t> &sizes, const Options &options = Options())

  Determines the sizes (i.e. the number of elements) of the decompressed output if a tensor with the given original sizes were to be decompressed with the given decompression options, specifically depending on the given cut-out. Note that when autocrop is enabled, we cannot exactly predict the final decompressed size so we assume nothing is cropped and return a safe upper bound.

## atc::DataType

enum class atc::DataType

  Represents the data type of the original or decompressed data. The data is always assumed to be stored using the local native byte order (little/big endian).

  Values:

  enumerator uint8

    8-bit unsigned integer

  enumerator uint16

    16-bit unsigned integer

  enumerator uint32

    32-bit unsigned integer

  enumerator uint64

    64-bit unsigned integer

  enumerator int8

    8-bit signed integer

  enumerator int16

    16-bit signed integer

  enumerator int32

    32-bit signed integer

  enumerator int64

    64-bit signed integer

  enumerator float32

    32-bit float (also known as `float`)

  enumerator float64

    64-bit float (also known as `double`)

template<typename dtype>
DataType atc::get_data_type()

  Returns the corresponding `atc::DataType` value depending on the template type.

## atc::version

const std::string atc::version = "1.1.2"

  The currently installed version of ATC.