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 ~~~~~~~~~ .. c: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 ~~~~~~~~~~~~~~~~~~~~~~ .. c:function:: 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 ^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^^^^^^^ .. c:function:: int dpcore_identifier_count() Return the number of registered camera identifiers. **Returns:** The number of registered camera identifiers. dpcore_get_identifiers ^^^^^^^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^ .. c:function:: 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: .. code-block:: cpp 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^^^^^^ .. c:function:: 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 ^^^^^^^^^^^^^^^^^^^^^ .. c:function:: 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.