C API Reference

This document provides a complete reference for the Jetraw C API libraries. The API consists of three main libraries:

  • DPCore: Image preparation library for preparing raw images before compression

  • Jetraw: Core compression and decompression library

  • Jetraw TIFF: Convenience library for working with TIFF files using Jetraw compression

All libraries use a common error handling mechanism through the dp_status enum type.

Common Types

dp_status

type dp_status

Enumeration type used by all Jetraw library functions to indicate operation status.

Success:

  • dp_success - Function completed without errors

General Errors:

  • dp_memory_error - Memory allocation failed

  • dp_not_initialized - Missing initialization

  • dp_unknown_error - Should usually not happen

License Errors:

  • dp_license_error - The license key could not be validated

File Errors:

  • dp_file_read_error - General error when file cannot be opened or read

  • dp_file_write_error - General error when file cannot be opened or written

  • dp_file_corrupt - File does not contain expected data

Parameter Errors:

  • dp_unknown_identifier - No parameters exist for given identifier

  • dp_parameter_error - Parameters cannot be used in given context

  • dp_image_too_small - Image has too few pixels for reliable preparation

  • dp_out_of_range - Parameter is out of range

TIFF-Specific Errors:

  • dp_tiff_file_cannot_open - TIFF file cannot be opened (e.g., file does not exist or is locked)

  • dp_tiff_not_initialized - Trying to use a TIFF file handle that was not properly opened or was already closed

  • dp_tiff_handle_in_use - Trying to open a TIFF file with a dp_tiff pointer that is still in use

  • dp_tiff_file_update_error - Could not update TIFF file (libtiff error)

  • dp_tiff_wrong_file_mode - Only “w” and “r” modes are accepted to open TIFF files

Image Errors:

  • dp_bad_image - The image data is invalid or not compatible with Jetraw compression

  • dp_unknown_cfa - No CFA enum exists with the given string

  • dp_bad_checksum - A checksum could not be verified

dp_status_description

const char *dp_status_description(dp_status status)

Returns a human-readable description of the given status code.

Parameters:

  • status - The status code to get a description for

Returns:

A null-terminated string describing the status code. This string should not be freed by the caller.

DPCore API

The DPCore library provides functions for preparing raw images before compression. Image preparation requires calibration parameters specific to the camera sensor used to capture the images.

Initialization and Configuration

dpcore_init

int dpcore_init()

Try to load noise parameter files from default locations.

Default locations are the current working directory, as well as an OS-dependent user data directory:

  • Windows: %APPDATA%\dpcore

  • macOS: $HOME/Library/Application Support/dpcore

  • Linux: ~/.config/dpcore

Parameter files are expected to have the extension .dat.

Returns:

The number of parameter files loaded.

dpcore_set_loglevel

void dpcore_set_loglevel(int level)

Set logging verbosity. By default, log output is sent to stdout. It can be redirected to a file by calling dpcore_set_logfile.

Parameters:

  • level - Logging level: 0=Off, 1=Informational, 2=Debugging

dpcore_set_logfile

dp_status dpcore_set_logfile(const CHARTYPE *file_path)

Write log output to file instead of to stdout. The log output will be written to the end of the file, i.e., the file is not overwritten.

Parameters:

  • file_path - Path to the log file

Returns:

  • dp_success - if all goes well

  • dp_file_write_error - on failure

Parameter Loading

dpcore_load_parameters

dp_status dpcore_load_parameters(const CHARTYPE *file_path)

Manually load noise parameters from a file.

Parameters:

  • file_path - Path to the calibration parameter file (.dat file)

Returns:

  • dp_success - if parameters were successfully retrieved

  • dp_file_read_error - if the file could not be opened or read

  • dp_file_corrupt - if the file could not be parsed

Image Preparation

dpcore_prepare_image

dp_status dpcore_prepare_image(uint16_t *imgbuf, int32_t imgsize, const char *identifier, float error_bound)

Prepare an image for efficient lossless compression.

Note

An image that already was prepared will not be modified a second time. Still, the function will return dp_success.

Parameters:

  • imgbuf - Contains the pixel values that will be overwritten by the preparation procedure

  • imgsize - Number of pixels in the image

  • identifier - Used to look up preparation parameters (calibration identifier)

  • error_bound - Maximum pixel modification in units of standard deviations (default: 1.0)

Returns:

  • dp_success - if the image data was prepared now or previously

  • dp_unknown_identifier - if no parameters could be found for the given identifier

  • dp_memory_error - if not enough memory could be allocated for the preparation

  • dp_image_too_small - if there are not enough pixels for reliable preparation

dpcore_embed_meta

dp_status dpcore_embed_meta(uint16_t *imgbuf, int32_t imgsize, const char *identifier, float error_bound)

Prepare an image for efficient lossless compression, but instead of performing the full noise replacement, only the metadata is embedded. This can be useful in situations where the image data is going to be compressed immediately and avoids redundant quantization/de-quantization.

Note

An image that already was prepared will not be modified a second time. Still, the function will return dp_success.

Parameters:

  • imgbuf - Contains the pixel values that will be overwritten by the preparation procedure

  • imgsize - Number of pixels in the image

  • identifier - Used to look up preparation parameters (calibration identifier)

  • error_bound - Maximum pixel modification in units of standard deviations (default: 1.0)

Returns:

  • dp_success - if the image data was prepared now or previously

  • dp_unknown_identifier - if no parameters could be found for the given identifier

  • dp_memory_error - if not enough memory could be allocated for the preparation

  • dp_image_too_small - if there are not enough pixels for reliable preparation

Identifier Management

dpcore_identifier_count

int dpcore_identifier_count()

Return the number of registered camera identifiers.

Returns:

The number of registered camera identifiers.

dpcore_get_identifiers

dp_status dpcore_get_identifiers(char *buf, int *bufsize)

Write list of camera identifiers to preallocated buffer.

Parameters:

  • buf - Output buffer. Cannot be null. When the function succeeds, the buffer contains a sequential list of null-terminated identifiers

  • bufsize - Pointer to the size of buf (in bytes). When the function returns, error or not, the pointee will contain the total number of bytes needed for all identifiers, including null-terminators. Hence, calling the function with *bufsize = 0 allows to determine the required size of buf

Returns:

  • dp_success - if all went well

  • dp_parameter_error - if bufsize is null

  • dp_memory_error - if buffer is too small or buf is null

Jetraw API

The Jetraw library provides core compression and decompression functions for prepared images.

Compression Functions

jetraw_encode

dp_status jetraw_encode(const uint16_t *pImgBuffer, uint32_t imgWidth, uint32_t imgHeight, char *pDstBuffer, int32_t *pDstLen)

Compresses the passed image.

Parameters:

  • pImgBuffer - Points to the pixel data of the image that should be compressed. Pointer must not be null

  • imgWidth - Width of the image in pixels

  • imgHeight - Height of the image in pixels

  • pDstBuffer - Pointer to output buffer. Must not be null

  • pDstLen - Points to maximum number of bytes that can be written to pDstBuffer. Rule of thumb: at least half the size of the uncompressed data. If the compression succeeds, the number of actual bytes is written here. Must not be null

Returns:

  • dp_success - if successful

  • dp_not_initialized - if the image data is not suitable for Jetraw compression

  • dp_parameter_error - if one of the pointers is null

  • dp_license_error - if no valid license was found

  • dp_unknown_identifier - if a bad combination of flags was provided

  • dp_memory_error - if memory allocation failed

Decompression Functions

jetraw_decode

dp_status jetraw_decode(const char *pSrcBuffer, int32_t srcLen, uint16_t *pImgBuffer, int32_t imgPixels)

Decompresses the passed image.

Parameters:

  • pSrcBuffer - Points to the bytes of the compressed image data. Must not be null

  • srcLen - Size of compressed data in bytes

  • pImgBuffer - Points to the output buffer. Must not be null

  • imgPixels - The maximum number of pixels that can be written to pImgBuffer

Returns:

  • dp_success - if successful

  • dp_parameter_error - if one of the pointers is null

  • dp_image_too_small - if imgPixels is smaller than the pixels of the compressed image

  • dp_memory_error - if memory allocation failed

Version Information

jetraw_version

const char *jetraw_version()

Returns the current Jetraw version.

Returns:

A null-terminated string containing the version information. This string should not be freed by the caller.

Jetraw TIFF API

The Jetraw TIFF library provides a convenience API for working with TIFF files that use Jetraw compression. It handles file I/O and multi-page TIFF files automatically.

Initialization and Configuration

jetraw_tiff_init

dp_status jetraw_tiff_init()

Registers Jetraw compression for libtiff. This function must be called before using any other Jetraw TIFF functions.

Returns:

dp_status indicating success or failure

jetraw_tiff_set_loglevel

void jetraw_tiff_set_loglevel(int level)

Set logging verbosity. By default, log output is sent to stdout. It can be redirected to a file by calling jetraw_tiff_set_logfile.

Parameters:

  • level - Logging level: 0=Off, 1=Informational, 2=Debugging

jetraw_tiff_set_logfile

dp_status jetraw_tiff_set_logfile(const CHARTYPE *file_path)

Write log output to file instead of to stdout. The log output will be written to the end of the file, i.e., the file is not overwritten.

Parameters:

  • file_path - Path to the log file

Returns:

  • dp_success - if all goes well

  • dp_file_write_error - on failure

jetraw_tiff_set_license

dp_status jetraw_tiff_set_license(const char *key)

Sets the license key to be used.

If the key is set to an empty string, Jetraw will look for the license key in a file license.txt, which should be placed in the following directory:

  • macOS: $HOME/Library/Application Support/jetraw

  • Windows: %APPDATA%\jetraw

  • Linux: ~/.config/jetraw

Parameters:

  • key - License key string, or empty string to use default location

Returns:

  • dp_success - if the license was set successfully

  • dp_license_error - if the key could not be validated

libtiff Integration

TIFFInitDotphoton

int TIFFInitDotphoton(TIFF *tif, int scheme)

Initializer for Jetraw codec for use with libtiff. Libraries that link directly with libtiff can make use of this function to register the codec.

This is typically done as follows:

TIFFRegisterCODEC(COMPRESSION_DOTPHOTON, "Dotphoton", TIFFInitDotphoton);
int success = TIFFIsCODECConfigured(COMPRESSION_DOTPHOTON);
if (success != 1) {
    std::cout << "Error: Codec could not be configured.\n";
}

All parameters are used internally by libtiff.

Parameters:

  • tif - TIFF file handle (used internally by libtiff)

  • scheme - Compression scheme (used internally by libtiff)

Returns:

Integer status code

jetraw_tiff_register_libtiff_with_name

dp_status jetraw_tiff_register_libtiff_with_name(const char *libname)

Register Jetraw codec with libtiff. This function is intended for use with applications that rely indirectly on libtiff, i.e., where the libtiff dynamic library was loaded into memory through a dependency, as is the case, e.g., for some Python modules.

The function looks in memory for a library with the given name and checks if the library contains functions TIFFGetVersion, TIFFRegisterCodec and TIFFIsCODECConfigured and uses those functions to register the codec, after which Jetraw-compressed TIFF files can be opened transparently.

Parameters:

  • libname - The name of the library that exposes the necessary functions of libtiff

Returns:

  • dp_success - if the registration is successful

  • dp_not_initialized - if the given library cannot be found in memory

  • dp_unknown_identifier - if the library in memory does not expose the required functions

  • dp_parameter_error - if the library in memory has an incompatible version

  • dp_unknown_error - if the codec could not be registered, i.e., TIFFIsCODECRegistered returns false

jetraw_tiff_register_libtiff

dp_status jetraw_tiff_register_libtiff()

Convenience function for registering with standard libtiff libraries. Calls jetraw_tiff_register_libtiff_with_name() with arguments "tiff" and "libtiff".

Returns:

dp_status indicating success or failure

File Operations

jetraw_tiff_open

dp_status jetraw_tiff_open(const CHARTYPE *tiff_path, int aoi_width, int aoi_height, const char *tiff_description, dp_tiff **handle, const char *mode)

Open a TIFF file for reading or writing.

Warning

If a file already exists at the given path, it will be overwritten and replaced with an empty file containing only the description.

Parameters:

  • tiff_path - The path of the file to be opened

  • aoi_width - Width of the image data that is going to be written to the file. It is assumed that all the image data in a multi-page TIFF will have the same dimensions

  • aoi_height - Height of the image data that is going to be written to the file

  • tiff_description - Description of the file. This goes unmodified into the corresponding TIFF file tag

  • handle - A handle to the file if successfully opened (output parameter)

  • mode - TIFF opening mode. Only “w” (write) and “r” (read) are accepted

Returns:

  • dp_success - if all goes well

  • dp_tiff_handle_in_use - if the dp_tiff object provided represents an open file

  • dp_tiff_file_cannot_open - if the file cannot be opened for writing (invalid path, file locked…)

  • dp_tiff_file_update_error - if the description tag of the file cannot be set

  • dp_license_error - if the license could not be validated, and compression is disabled

  • dp_tiff_wrong_file_mode - if open mode is different than “w” and “r”

jetraw_tiff_close

dp_status jetraw_tiff_close(dp_tiff **handle)

Closes a TIFF file and frees the file handle.

Note

Once a file has been closed, no further images can be appended to it through this API.

Parameters:

  • handle - Handle of the file to be closed. Will be set to null upon success

Returns:

  • dp_success - if the file was closed successfully (and all data written to disk)

  • dp_tiff_not_initialized - if handle does not represent an open file

Page Operations

jetraw_tiff_append

dp_status jetraw_tiff_append(const dp_tiff *handle, const uint16_t *img_buffer)

Compresses an image and appends it as a new image/page to an open TIFF file.

Parameters:

  • handle - Handle of the file to which the image is to be appended

  • img_buffer - Buffer that holds the uncompressed image data. Must be of the dimensions supplied to jetraw_tiff_open() when handle was obtained

Returns:

  • dp_success - if the image was successfully compressed and appended to the file

  • dp_tiff_not_initialized - if handle does not represent an open TIFF file

  • dp_params_not_loaded - if compression parameters are not loaded

  • dp_tiff_file_update_error - if the new page could not be appended to the file

jetraw_tiff_read_page

dp_status jetraw_tiff_read_page(const dp_tiff *handle, uint16_t *img_buffer, int page)

Reads a TIFF compressed page image and saves the uncompressed page to img_buffer.

Parameters:

  • handle - Handle of the file from which the image is to be read

  • img_buffer - Buffer that will be used to save the uncompressed image data. Must be of the dimensions supplied to jetraw_tiff_open() when handle was obtained

  • page - Indicates the index of the page to be read (0-based)

Returns:

  • dp_success - if the image was successfully read and decompressed

  • dp_tiff_not_initialized - if handle does not represent an open TIFF file

  • dp_file_read_error - if TIFF page is not compressed, reading is not possible, or there is a problem with TIFFReadEncodedStrip

Metadata Functions

jetraw_tiff_get_width

int jetraw_tiff_get_width(dp_tiff *handle)

Gets width value from dp_tiff struct and returns it.

Parameters:

  • handle - Handle of the TIFF file

Returns:

If handle exists and magic number is correct, the image width is returned.

jetraw_tiff_get_height

int jetraw_tiff_get_height(dp_tiff *handle)

Gets height value from dp_tiff struct and returns it.

Parameters:

  • handle - Handle of the TIFF file

Returns:

If handle exists and magic number is correct, the image height is returned.

jetraw_tiff_get_pages

int jetraw_tiff_get_pages(dp_tiff *handle)

Gets number of pages value from dp_tiff struct and returns it.

Parameters:

  • handle - Handle of the TIFF file

Returns:

If handle exists and magic number is correct, the image number of pages is returned.