nvTiff Documentation¶
Introduction¶
nvTIFF is a GPU accelerated TIFF(Tagged Image File Format) encode/decode library built on the CUDA platform. The library is supported on Volta+ GPU architectures. It supports the following TIFF feature set:
Note
Throughout this document, the terms “CPU” and “Host” are used synonymously. Similarly, the terms “GPU” and “Device” are synonymous.
Decoder¶
Planar Separate and Contiguous modes
Up to 16 Samples per pixel
Compression
JPEG(via nvJPEG)
Deflate(via nvCOMP)
LZW
None (uncompressed)
Color space can be - Grayscale, RGB, YCbCr, RGB Palette. When compressed data is in YCbCr or Palette mode, the library will convert the decoded output to RGB colorspace.
TIFF files can use either tiles or strips.
Up to 32 bits per sample when compression type is : None, Deflate, LZW. Up to 8 bits per sample when compression type is JPEG.
TIFFs with multiple images having different properties.
APIs to retrieve GeoTIFF Metadata
The below diagram represents nvTIFF decoder’s interaction with other cuda libraries such as nvJPEG and nvCOMP (for DEFLATE decompression). The user application will call cuda APIs to create decode output buffers prior to calling nvTIFF decoder.
nvTiff decoder overview¶
Encoder¶
Planar Contiguous mode only.
Up to 4 samples per pixel.
LZW compression.
Compressed data is organized in strips.
Up to 32 bits per sample.
Multiple Images in a TIFF file. All images which are to be compressed must have identical properties.
nvTiff encoder overview¶
Applying GPU Acceleration to TIFF files¶
A TIFF file may contain single or multiple images. Each of these images are subdivided into strips or tiles. Each of these strips/tiles can be encoded/decoded in parallel thereby providing speed up over CPU implementations.
When decoding TIFF files with multiple images with identical metadata, the strips/tiles across all images can be decoded as part of a single batched CUDA kernel. The converse is true for encoding, each strip/tile can be compressed in parallel. The compressed tiles/strips can be stitched to create a TIFF file
Prerequisites¶
CUDA Toolkit version 11.0 and above.
CUDA Driver version r450 and above.
nvCOMP 2.6+ (required when compression is deflate).
Platforms Supported¶
Linux versions:
Architecture |
Distribution Information |
||||
|---|---|---|---|---|---|
Name |
Version |
Kernel |
GCC |
GLIBC |
|
x86_64 |
RHEL / Rocky Linux |
9.4 |
5.14 |
11.3.1 |
2.34 |
8.10 |
4.18 |
8.5.0 |
2.28 |
||
Ubuntu |
24.04 |
6.8.0 |
13.2.0 |
2.39 |
|
22.04 |
6.5.0 |
11.2.0 |
2.34 |
||
20.04 |
5.15.0 |
9.3.0 |
2.31 |
||
OpenSUSE Leap |
15.6 |
6.4.0 |
7.5.0 |
2.38 |
|
SUSE SLES |
15 |
6.4.0 |
7.5.0 |
2.31 |
|
Debian |
11.10 |
5.10.0 |
10.2.1 |
2.31 |
|
10.13 |
4.19.0 |
8.3.0 |
2.28 |
||
Fedora |
39 |
6.5.6 |
13.2.1 |
2.38 |
|
arm64-sbsa |
RHEL |
9.4 |
5.14 |
11.3.1 |
2.34 |
8.10 |
4.18 |
8.5.0 |
2.28 |
||
24.04 |
6.8.0 |
13.2.0 |
2.35 |
||
Ubuntu |
22.04 |
5.15.0 |
11.4.0 |
2.35 |
|
20.04 |
5.4.0 |
9.4.0 |
2.31 |
||
SUSE SLES |
15.6 |
6.4.0 |
7.5.0 |
2.38 |
|
Windows versions:
Windows 10, Windows 11 and Windows Server 2023
WSL
Tegra
Supported on Jetpack v5.1.3 and above.
Installing nvTIFF¶
NVIDIA DevZone¶
nvTIFF binaries and download instructions are available here - https://developer.nvidia.com/nvtiff-downloads.
For Linux, the binaries are available in both archive (.tar.xz) and package manager formats(.deb, .rpm)
For Windows, the binaries are available in both archive (.zip) and windows installer formats.
PyPi¶
nvTIFF binaries are available on PyPi and can be installed through pip using the below commands. This makes it easy for the library to be used in python environments.
To install nvTIFF for CUDA 12.x
python3 -m pip install nvidia-nvtiff-cu12
To install nvTIFF for CUDA 12.x on Tegra platforms
python3 -m pip install nvidia-nvtiff-tegra-cu12
To install nvTIFF for CUDA 11.x
python3 -m pip install nvidia-nvtiff-cu11
To install nvTIFF for CUDA 11.x on Tegra platforms
python3 -m pip install nvidia-nvtiff-tegra-cu11
Quick Start Guide¶
This section will explain how to use decoder and encoder APIs in a few quick steps. The API details will be covered in the next section.
Note
Link to nvTIFF Samples: https://github.com/NVIDIA/CUDALibrarySamples/tree/master/nvTIFF
Please note that since the decoding and encoding of TIFF images are two fundamentally different problems the APIs for decoding and encoding are also different and independent.
nvTIFF Decode¶
The library reads the file from disk and loads the image data to device memory.
Create instances of the following -
nvtiffStream_t - is used to parse the bitstream and store the bitstream metadata
nvtiffDecoder_t - is used to store the work buffers required for decode
nvtiffStream_t nvtiff_stream;
nvtiffDecoder_t nvtiff_decoder;
nvtiffStreamCreate(&nvtiff_stream);
nvtiffDecoderCreateSimple(&nvtiff_decoder);
Use the nvtiffStreamParseFromFile API to parse the tiff file from disk.
// char *fname, is the tiff file name
nvtiffStatus_t status = nvtiffStreamParseFromFile(fname, nvtiff_stream));
// make sure that nvtiffStreamParseFromFile returns NVTIFF_STATUS_SUCCESS before proceeding to the next step
Extract the tiff file meta data.
nvtiffFileInfo_t file_info;
nvtiffStatus_t status = nvtiffStreamGetFileInfo(tiff_stream, &file_info);
//nvTiff requires all the images (subfiles) in the same file to have the same properties.
Allocate decode output on device.
// allocate device memory for images
unsigned char **image_out = NULL;
const size_t image_size = sizeof(**image_out)*file_info.image_width *
file_info.image_height *
(file_info.bits_per_pixel/8);
// we are decoding all the images in file "fname" from
// subfile no. "frameBeg" to subfile no. "frameEnd"
frame_beg = fmax(frame_beg, 0);
frame_end = fmin(frame_end, file_info.num_images - 1);
const int num_decoded_images = frame_end - frame_beg + 1;
image_out = (unsigned char **)Malloc(sizeof(*image_out)*num_decoded_images);
for(unsigned int i = 0; i < nDecode; i++) {
CHECK_CUDA(cudaMalloc(image_out + i, image_size));
}
Call nvtiffDecode function to decode the data or range of data from files.
if (!decodeRange) {
nvtiffStatus_t status = nvtiffDecode(nvtiff_stream, nvtiff_decoder, image_out, stream);
} else {
nvtiffStatus_t status = nvtiffDecodeRange(nvtiff_stream, nvtiff_decoder, frame_beg, num_decoded_images, image_out, stream);
}
cudaStreamSynchronize(stream);
// cudaStreamSynchronize is requires since the decode APIs are asychronous with respect to the host
Go to step 1 to decode another image. Once all images are decoded, release nvTIFF the library resources by calling the corresponding destroy APIs.
nvTIFF Encode¶
Initialize the library handles and encoder parameters listed below:
// unsigned char **images_d is an host array of "nSubFiles" pointers
// to device buffers containing "nSubFiles" uncompressed images; each
// image has the same number of rows (nrow), of columns (ncol)
// and pixel size in bytes (pixelSize)
// for example let's partition the images in strips of four rows each
unsigned int encRowsPerStrip = 4;
unsigned int nStripOut = DIV_UP(nrow, encRowsPerStrip);
unsigned int totStrips = nSubFiles*nStripOut;
// initial estimate on the maximim
// size of compressed strips
unsigned long long encStripAllocSize = rowsPerStrip*ncol*(pixelSize);
// allocate encoding output buffers;
CHECK_CUDA(cudaMalloc(&stripSize_d, sizeof(*stripSize_d)*totStrips));
CHECK_CUDA(cudaMalloc(&stripOffs_d, sizeof(*stripOffs_d)*totStrips));
CHECK_CUDA(cudaMalloc(&stripData_d, sizeof(*stripData_d)*totStrips*encStripAllocSize));
// create encoding context
nvTiffEncodeCtx_t *ctx = nvTiffEncodeCtxCreate(devId, nSubFiles, nStripOut);
Call nvTiffEncode function to encode. Since we cant’t know in advance the size of the compressed strips, we first try to encode in the buffers allocated based on our initial estimate. If one or more strips require more memory than “encStripAllocSize” bytes then we need to restart the encoding process with a larger buffer. In such a case, after the encoding fails, the minimum size required for the encoding to succeed is passed from the library to the user in the context field stripSizeMax. This way the encoding process can only fail once due to an output buffer being too small. After a successful encoding (nvTiffEncodeFinalize() returning NVTIFF_ENCODE_SUCCESS), the compressed strip data, offsets and sizes are returned in the buffers stripData_d, stripOffs_d and stripSize_d. In addition, the total size of the compressed strip data is also returned in ctx->stripSizeTot. Please note that you need to synchronize on stream
streambefore accessing those buffers.
int i = 0;
do {
rv = nvTiffEncode(ctx,
nrow,
ncol,
pixelSize,
encRowsPerStrip,
nSubFiles,
imageOut_d,
encStripAllocSize,
stripSize_d,
stripOffs_d,
stripData_d,
stream);
if (rv != NVTIFF_ENCODE_SUCCESS) {
// ERROR, WHILE ENCODING IMAGES!
}
rv = nvTiffEncodeFinalize(ctx, stream);
if (rv != NVTIFF_ENCODE_SUCCESS) {
if (rv == NVTIFF_ENCODE_COMP_OVERFLOW) {
if (i == 1) {
// UNKNOWN ERROR, nvTiffEncode() SHOULDN'T OVERFLOW TWICE!
}
encStripAllocSize = ctx->stripSizeMax;
nvTiffEncodeCtxDestroy(ctx);
cudaFree(stripData_d);
cudaMalloc(&stripData_d,
sizeof(*stripData_d)*totStrips*encStripAllocSize);
ctx = nvTiffEncodeCtxCreate(dev, ...);
i++;
} else {
// ERROR WHILE FINALIZING COMPRESSED IMAGES
}
}
} while(rv == NVTIFF_ENCODE_COMP_OVERFLOW);
CHECK_CUDA(cudaStreamSynchronize(stream));
Write the compress image to TIFF file.
// copy compressed data from the device to the host
unsigned long long *stripSize_h = (unsigned long long *)Malloc(sizeof(*stripSize_h)*totStrips);
CHECK_CUDA(cudaMemcpy(stripSize_h,
stripSize_d,
sizeof(*stripSize_h)*totStrips,
cudaMemcpyDeviceToHost));
unsigned long long *stripOffs_h = (unsigned long long *)Malloc(sizeof(*stripOffs_h)*totStrips);
CHECK_CUDA(cudaMemcpy(stripOffs_h,
stripOffs_d,
sizeof(*stripOffs_h)*totStrips,
cudaMemcpyDeviceToHost));
unsigned char *stripData_h = (unsigned char *)Malloc(sizeof(*stripData_h)*ctx->stripSizeTot);
CHECK_CUDA(cudaMemcpy(stripData_h,
stripData_d,
ctx->stripSizeTot,
cudaMemcpyDeviceToHost));
// write output file
nvTiffWriteFile("outFile.tif",
VER_REG_TIFF,
nSubFiles,
nrow,
ncol,
encRowsPerStrip,
samplesPerPixel,
bitsPerSample,
photometricInt,
planarConf,
stripSize_h,
stripOffs_h,
stripData_h);
Tiff Decode / Encode Demo example¶
The binary nvTiff_exmaple provides a complete and detailed usage example for the encoding and decoding capabilities of the nvTIFF library.
Usage:
nvTiff_example [options] -f|--file <TIFF_FILE>
General options:
-d DEVICE_ID
--device DEVICE_ID
Specifies the GPU to use for images decoding/encoding.
Default: device 0 is used.
-v
--verbose
Prints some information about the decoded TIFF file.
-h
--help
Prints this help
Decoding options:
-f TIFF_FILE
--file TIFF_FILE
Specifies the TIFF file to decode. The code supports both single and multi-image
tiff files with the following limitations:
* color space must be either Grayscale (PhotometricInterp.=1) or RGB (=2)
* image data compressed with LZW (Compression=5) or uncompressed
* pixel components stored in "chunky" format (RGB..., PlanarConfiguration=1)
for RGB images
* image data must be organized in Strips, not Tiles
* pixels of RGB images must be represented with at most 4 components
* each component must be represented exactly with:
* 8 bits for LZW compressed images
* 8, 16 or 32 bits for uncompressed images
* all images in the file must have the same properties
-b BEG_FRM
--frame-beg BEG_FRM
Specifies the image id in the input TIFF file to start decoding from. The image
id must be a value between 0 and the total number of images in the file minus 1.
Values less than 0 are clamped to 0.
Default: 0
-e END_FRM
--frame-end END_FRM
Specifies the image id in the input TIFF file to stop decoding at (included).
The image id must be a value between 0 and the total number of images in the
file minus 1. Values greater than num_images-1 are clamped to num_images-1.
Default: num_images-1.
-m
--memtype TYPE
Specifies the type of memory used to hold the TIFF file content: pinned or
pageable. Pinned memory is used if 'p' is specified. Pageable memory is used if
'r' is specified. In case of pinned memory, file content is not copied to
device memory before the decoding process (with a resulting performance impact)
unless the option -c is also specified (see below).
Defualt: r (pageable)
-c
--copyh2d
Specifies to copy the file data to device memory in case the -m option specifies
to use pinned memory. In case of pageable memory this option has no effect.
Default: off.
--decode-out NUM_OUT
Enables the writing of selected images from the decoded input TIFF file into
separate BMP files for inspection. If no argument is passed, only the first
image is written to disk, otherwise the first NUM_OUT images are written.
Output files are named outImage_0.bmp, outImage_1.bmp...
Defualt: disabled.
Encoding options:
-E
--encode
This option enables the encoding of the raster images obtained by decoding the
input TIFF file. The images are divided into strips, compressed with LZW and,
optionally, written into an output TIFF file.
Default: disabled.
-r
--rowsxstrip
Specifies the number of consecutive rows to use to divide the images into
strips. Each image is divided in strips of the same size (except possibly the
last strip) and then the strips are compressed as independent byte streams.
This option is ignored if -E is not specified.
Default: 1.
-s
--stripalloc
Specifies the initial estimate of the maximum size of compressed strips. If
during compression one or more strips require more space, the compression is
aborted and restarted automatically with a safe estimate.
This option is ignored if -E is not specified.
Default: the size, in bytes, of a strip in the uncompressed images.
--encode-out
Enables the writing of the compressed images to an output TIFF file named
outFile.tif.
This option is ignored if -E is not specified.
Defualt: disabled.
Type Declarations¶
nvTIFF Encode API Return Status Codes¶
The return codes of the nvTIFF Encode APIs are listed below:
#define NVTIFF_ENCODE_SUCCESS (0)
#define NVTIFF_ENCODE_INVALID_CTX (1)
#define NVTIFF_ENCODE_INVALID_STRIP_NUM (2)
#define NVTIFF_ENCODE_COMP_OVERFLOW (3)
#define NVTIFF_ENCODE_COMP_STRIP_TOO_LONG (4)
Description the Return Codes
Return Code |
Description |
|---|---|
NVTIFF_ENCODE_SUCCESS (0) |
The API call has finished successfully. Note that many of the calls are asynchronous and some of the errors may be seen only after synchronization. |
NVTIFF_ENCODE_INVALID_CTX (1) |
Invalid CTX. |
NVTIFF_ENCODE_INVALID_STRIP_NUM (2) |
Invalid strip number |
NVTIFF_ENCODE_COMP_OVERFLOW (3) |
overflow during compression |
NVTIFF_ENCODE_COMP_STRIP_TOO_LONG (4) |
Too long strip |
nvTIFF Write API Return Status Codes¶
The return codes of the nvTIFF Write APIs are listed below:
#define NVTIFF_WRITE_SUCCESS (0)
#define NVTIFF_WRITE_UNSUPP_PLANAR_CONF (1)
#define NVTIFF_WRITE_UNSUPP_PHOTOMETRIC_INT (2)
Description the Return Codes
Return Code |
Description |
|---|---|
NVTIFF_WRITE_SUCCESS (0) |
The API call has finished successfully. Note that many of the calls are asynchronous and some of the errors may be seen only after synchronization. |
NVTIFF_WRITE_UNSUPP_PLANAR_CONF (1) |
if the value of planarConf parameter is not equal to 1;. |
NVTIFF_WRITE_UNSUPP_PHOTOMETRIC_INT (2) |
if the value of photometricInt parameter is neither 1 nor 2; |
Decode API Return Status Codes¶
The return codes of the nvTiff Decode APIs are listed below:
typedef enum {
NVTIFF_STATUS_SUCCESS = 0,
NVTIFF_STATUS_NOT_INITIALIZED = 1,
NVTIFF_STATUS_INVALID_PARAMETER = 2,
NVTIFF_STATUS_BAD_TIFF = 3,
NVTIFF_STATUS_TIFF_NOT_SUPPORTED = 4,
NVTIFF_STATUS_ALLOCATOR_FAILURE = 5,
NVTIFF_STATUS_EXECUTION_FAILED = 6,
NVTIFF_STATUS_ARCH_MISMATCH = 7,
NVTIFF_STATUS_INTERNAL_ERROR = 8,
NVTIFF_STATUS_NVCOMP_NOT_FOUND = 9,
NVTIFF_STATUS_NVJPEG_NOT_FOUND = 10,
NVTIFF_STATUS_TAG_NOT_FOUND = 11,
NVTIFF_STATUS_PARAMETER_OUT_OF_BOUNDS = 12,
} nvtiffStatus_t;
Description the Return Codes
Return Code |
Description |
|---|---|
NVTIFF_STATUS_SUCCESS (0) |
The API call has finished successfully. Note that many of the calls are asynchronous and some of the errors may be seen only after synchronization. |
NVTIFF_STATUS_NOT_INITIALIZED (1) |
The library handle was not initialized. |
NVTIFF_STATUS_INVALID_PARAMETER (2) |
Wrong parameter was passed. For example, a null pointer as input data, or an invalid enum value |
NVTIFF_STATUS_BAD_TIFF (3) |
Cannot parse the TIFF stream. Likely due to a corruption that cannot be handled |
NVTIFF_STATUS_TIFF_NOT_SUPPORTED (4) |
Attempting to decode a TIFF stream that is not supported by the nvTIFF library. |
NVTIFF_STATUS_ALLOCATOR_FAILURE (5) |
The user-provided allocator functions, for either memory allocation or for releasing the memory, returned a non-zero code. |
NVTIFF_STATUS_EXECUTION_FAILED (6) |
Error during the execution of the device tasks. |
NVTIFF_STATUS_ARCH_MISMATCH (7) |
The device capabilities are not enough for the set of input parameters provided. |
NVTIFF_STATUS_INTERNAL_ERROR (8) |
Unknown error occured in the library. |
NVTIFF_STATUS_NVCOMP_NOT_FOUND (9) |
nvTiff is unable to load the nvcomp library. |
NVTIFF_STATUS_NVJPEG_NOT_FOUND (10) |
nvTiff is unable to load the nvjpeg library. |
NVTIFF_STATUS_TAG_NOT_FOUND (11) |
nvTiff is unable to find information about the provided tag |
NVTIFF_STATUS_PARAMETER_OUT_OF_BOUNDS (12) |
Provided parameter is outside the range of possible values |
TIFF Tag Data Type¶
typedef enum nvtiffTagDataType {
NVTIFF_TAG_TYPE_BYTE = 1,
NVTIFF_TAG_TYPE_ASCII = 2,
NVTIFF_TAG_TYPE_SHORT = 3,
NVTIFF_TAG_TYPE_LONG = 4,
NVTIFF_TAG_TYPE_RATIONAL = 5,
NVTIFF_TAG_TYPE_SBYTE = 6,
NVTIFF_TAG_TYPE_UNDEFINED = 7,
NVTIFF_TAG_TYPE_SSHORT = 8,
NVTIFF_TAG_TYPE_SLONG = 9,
NVTIFF_TAG_TYPE_SRATIONAL = 10,
NVTIFF_TAG_TYPE_FLOAT = 11,
NVTIFF_TAG_TYPE_DOUBLE = 12,
NVTIFF_TAG_TYPE_LONG8 = 16,
NVTIFF_TAG_TYPE_SLONG8 = 17,
NVTIFF_TAG_TYPE_IFD8 = 18,
} nvtiffTagDataType_t;
nvtiffTagDataType_t corresponds to the datatype for a TIFF tag.
GeoTIFF Keys¶
typedef enum nvtiffGeoKeys
{
// GeoTIFF Configuration Keys
NVTIFF_GEOKEY_GT_MODEL_TYPE = 1024,
NVTIFF_GEOKEY_GT_RASTER_TYPE = 1025,
NVTIFF_GEOKEY_GT_CITATION = 1026,
// Geodetic CRS Parameter Keys
NVTIFF_GEOKEY_GEODETIC_CRS = 2048,
NVTIFF_GEOKEY_GEODETIC_CITATION = 2049,
NVTIFF_GEOKEY_GEODETIC_DATUM = 2050,
NVTIFF_GEOKEY_PRIME_MERIDIAN = 2051,
NVTIFF_GEOKEY_GEOG_LINEAR_UNITS = 2052,
NVTIFF_GEOKEY_GEOG_LINEAR_UNIT_SIZE = 2053,
NVTIFF_GEOKEY_GEOG_ANGULAR_UNITS = 2054,
NVTIFF_GEOKEY_GEOG_ANGULAR_UNIT_SIZE = 2055,
NVTIFF_GEOKEY_ELLIPSOID = 2056,
NVTIFF_GEOKEY_ELLIPSOID_SEMI_MAJOR_AXIS = 2057,
NVTIFF_GEOKEY_ELLIPSOID_SEMI_MINOR_AXIS = 2058,
NVTIFF_GEOKEY_ELLIPSOID_INV_FLATTENING = 2059,
NVTIFF_GEOKEY_GEOG_AZIMUTH_UNITS = 2060,
NVTIFF_GEOKEY_PRIME_MERIDIAN_LONG = 2061,
// Projected CRS Parameter Keys
NVTIFF_GEOKEY_PROJECTED_CRS = 3072,
NVTIFF_GEOKEY_PROJECTED_CITATION = 3073,
NVTIFF_GEOKEY_PROJECTION = 3074,
NVTIFF_GEOKEY_PROJ_METHOD = 3075,
NVTIFF_GEOKEY_PROJ_LINEAR_UNITS = 3076,
NVTIFF_GEOKEY_PROJ_LINEAR_UNIT_SIZE = 3077,
NVTIFF_GEOKEY_PROJ_STD_PARALLEL1 = 3078,
NVTIFF_GEOKEY_PROJ_STD_PARALLEL = 3078,
NVTIFF_GEOKEY_PROJ_STD_PARALLEL2 = 3079,
NVTIFF_GEOKEY_PROJ_NAT_ORIGIN_LONG = 3080,
NVTIFF_GEOKEY_PROJ_ORIGIN_LONG = 3080,
NVTIFF_GEOKEY_PROJ_NAT_ORIGIN_LAT = 3081,
NVTIFF_GEOKEY_PROJ_ORIGIN_LAT = 3081,
NVTIFF_GEOKEY_PROJ_FALSE_EASTING = 3082,
NVTIFF_GEOKEY_PROJ_FALSE_NORTHING = 3083,
NVTIFF_GEOKEY_PROJ_FALSE_ORIGIN_LONG = 3084,
NVTIFF_GEOKEY_PROJ_FALSE_ORIGIN_LAT = 3085,
NVTIFF_GEOKEY_PROJ_FALSE_ORIGIN_EASTING = 3086,
NVTIFF_GEOKEY_PROJ_FALSE_ORIGIN_NORTHING = 3087,
NVTIFF_GEOKEY_PROJ_CENTER_LONG = 3088,
NVTIFF_GEOKEY_PROJ_CENTER_LAT = 3089,
NVTIFF_GEOKEY_PROJ_CENTER_EASTING = 3090,
NVTIFF_GEOKEY_PROJ_CENTER_NORTHING = 3091,
NVTIFF_GEOKEY_PROJ_SCALE_AT_NAT_ORIGIN = 3092,
NVTIFF_GEOKEY_PROJ_SCALE_AT_ORIGIN = 3092,
NVTIFF_GEOKEY_PROJ_SCALE_AT_CENTER = 3093,
NVTIFF_GEOKEY_PROJ_AZIMUTH_ANGLE = 3094,
NVTIFF_GEOKEY_PROJ_STRAIGHT_VERT_POLE_LONG = 3095,
// Vertical CRS Parameter Keys (4096-5119)
NVTIFF_GEOKEY_VERTICAL = 4096,
NVTIFF_GEOKEY_VERTICAL_CITATION = 4097,
NVTIFF_GEOKEY_VERTICAL_DATUM = 4098,
NVTIFF_GEOKEY_VERTICAL_UNITS = 4099,
NVTIFF_GEOKEY_BASE = 32768,
NVTIFF_GEOKEY_END = 65535
} nvtiffGeoKey_t;
nvtiffGeoKey_t corresponds to various geo keys listed in the GeoTIFF specification.
User can refer to the GeoTIFF specification for additional details.
GeoTIFF Key Datatype¶
typedef enum nvtiffGeoKeyDataType {
NVTIFF_GEOKEY_TYPE_SHORT=1,
NVTIFF_GEOKEY_TYPE_ASCII=2,
NVTIFF_GEOKEY_TYPE_DOUBLE=3,
NVTIFF_GEOKEY_TYPE_UNKNOWN=4
} nvtiffGeoKeyDataType_t;
nvtiffGeoKeyDataType_t corresponds to a datatype for a geo key.
Device Allocator Interface¶
typedef int (*nvtiffDeviceMallocAsync)(void* ctx, void **ptr, size_t size, cudaStream_t stream);
typedef int (*nvtiffDeviceFreeAsync)(void* ctx, void *ptr, size_t size, cudaStream_t stream);
typedef struct {
nvtiffDeviceMallocAsync device_malloc;
nvtiffDeviceFreeAsync device_free;
void *device_ctx;
} nvtiffDeviceAllocator_t;
Custom device allocator supports stream ordered allocation and user defined context information *device_ctx. When
invoking the device allocators, nvTiff will pass *device_ctx as input to the device allocator.
Pinned Allocator Interface¶
typedef int (*nvtiffPinnedMallocAsync)(void* ctx, void **ptr, size_t size, cudaStream_t stream);
typedef int (*nvtiffPinnedFreeAsync)(void* ctx, void *ptr, size_t size, cudaStream_t stream);
typedef struct {
nvtiffPinnedMallocAsync pinned_malloc;
nvtiffPinnedFreeAsync pinned_free;
void *pinned_ctx;
} nvtiffPinnedAllocator_t;
Custom pinned allocator supports stream ordered allocation and user defined context information *pinned_ctx. When
invoking the pinned allocators, nvTiff will pass *pinned_ctx as input to the pinned allocator.
Image Type¶
typedef enum {
NVTIFF_IMAGETYPE_REDUCED_IMAGE = 0b0001,
NVTIFF_IMAGETYPE_PAGE = 0b0010,
NVTIFF_IMAGETYPE_MASK = 0b0100,
NVTIFF_IMAGETYPE_ENUM_FORCE_UINT32 = 0xFFFFFFFF,
} nvtiffImageType;
typedef uint32_t nvtiffImageType_t;
nvtiffImageType enum corresponds to the NewSubfiletype (254) tag defined in the TIFF specification.
Compression Type¶
typedef enum nvtiffCompression {
NVTIFF_COMPRESSION_UNKNOWN = 0,
NVTIFF_COMPRESSION_NONE = 1,
NVTIFF_COMPRESSION_LZW = 5,
NVTIFF_COMPRESSION_JPEG = 7,
NVTIFF_COMPRESSION_ADOBE_DEFLATE = 8,
NVTIFF_COMPRESSION_DEFLATE = 32946,
} nvtiffCompression_t;
nvtiffCompression_t enum corresponds to the Compression (259) tag defined in the TIFF specification.
Photometric Interpretation¶
typedef enum nvtiffPhotometricInt {
NVTIFF_PHOTOMETRIC_UNKNOWN = -1,
NVTIFF_PHOTOMETRIC_MINISWHITE = 0,
NVTIFF_PHOTOMETRIC_MINISBLACK = 1,
NVTIFF_PHOTOMETRIC_RGB = 2,
NVTIFF_PHOTOMETRIC_PALETTE = 3,
NVTIFF_PHOTOMETRIC_MASK = 4,
NVTIFF_PHOTOMETRIC_SEPARATED = 5,
NVTIFF_PHOTOMETRIC_YCBCR = 6,
}nvtiffPhotometricInt_t;
nvtiffPhotometricInt_t enum corresponds to the PhotometricInterpretation (262) tag defined in the TIFF specification.
Planar Configuration¶
typedef enum nvtiffPlanarConfig {
NVTIFF_PHOTOMETRIC_UNKNOWN = -1,
NVTIFF_PHOTOMETRIC_MINISWHITE = 0,
NVTIFF_PHOTOMETRIC_MINISBLACK = 1,
NVTIFF_PHOTOMETRIC_RGB = 2,
NVTIFF_PHOTOMETRIC_PALETTE = 3,
NVTIFF_PHOTOMETRIC_MASK = 4,
NVTIFF_PHOTOMETRIC_SEPARATED = 5,
NVTIFF_PHOTOMETRIC_YCBCR = 6,
} nvtiffPlanarConfig_t;
nvtiffPlanarConfig_t enum corresponds to the PlanarConfiguration (284) tag defined in the TIFF specification.
Sample Format¶
typedef enum nvtiffSampleFormat {
NVTIFF_SAMPLEFORMAT_UNKNOWN = 0,
NVTIFF_SAMPLEFORMAT_UINT = 1,
NVTIFF_SAMPLEFORMAT_INT = 2,
NVTIFF_SAMPLEFORMAT_IEEEFP = 3,
NVTIFF_SAMPLEFORMAT_VOID = 4,
NVTIFF_SAMPLEFORMAT_COMPLEXINT = 5,
NVTIFF_SAMPLEFORMAT_COMPLEXIEEEFP = 6
} nvtiffSampleFormat_t;
nvtiffSampleFormat_t enum corresponds to the SampleFormat (339) tag defined in the TIFF specification.
TIFF File Information¶
typedef struct nvtiffFileInfo {
uint32_t num_images;
uint32_t image_width;
uint32_t image_height;
nvtiffPhotometricInt_t photometric_int;
nvtiffPlanarConfig_t planar_config;
uint16_t samples_per_pixel;
uint16_t bits_per_pixel; // SUM(bits_per_sample)
uint16_t bits_per_sample[MAX_NUM_SAMPLES];
nvtiffSampleFormat_t sample_format[MAX_NUM_SAMPLES];
} nvtiffFileInfo_t;
nvtiffFileInfo_t enum is used to retrieve some of the TIFF file metadata. This information can be used for allocating decode output buffers.
TIFF Image Information¶
typedef struct nvtiffImageInfo {
nvtiffImageType_t image_type;
uint32_t image_width;
uint32_t image_height;
nvtiffCompression_t compression;
nvtiffPhotometricInt_t photometric_int;
nvtiffPlanarConfig_t planar_config;
uint16_t samples_per_pixel;
uint16_t bits_per_pixel; // SUM(bits_per_sample)
uint16_t bits_per_sample[MAX_NUM_SAMPLES];
nvtiffSampleFormat_t sample_format[MAX_NUM_SAMPLES];
} nvtiffImageInfo_t;
nvtiffImageInfo_t contains some additional metadata of an image stored in a TIFF file.
TIFF Geometry Type¶
typedef enum nvtiffImageGeometryType {
NVTIFF_IMAGE_STRIPED = 0,
NVTIFF_IMAGE_TILED = 1,
} nvtiffImageGeometryType_t;
nvtiffImageGeometryType_t specifies whether a tiff file uses strips or tiles
TIFF Geometry Information¶
typedef struct nvtiffImageGeometry {
nvtiffImageGeometryType_t type;
uint32_t image_depth;
uint32_t strile_width; // strile_width = image_width for strips
uint32_t strile_height;
uint32_t strile_depth; // strile_depth = image_depth for strips
uint32_t num_striles_per_plane;
uint32_t num_striles;
} nvtiffImageGeometry_t;
Stores image geometry along with strip/tile dimensions. When the geometry type is NVTIFF_IMAGE_STRIPED, strile_width is to image width.
Decode Output Format¶
typedef enum nvtiffOutputFormat {
NVTIFF_OUTPUT_UNCHANGED_I = 0, // Interleaved channels
NVTIFF_OUTPUT_RGB_I_UINT8 = 1, // Interleaved RGB with 8 bits per channel
NVTIFF_OUTPUT_RGB_I_UINT16 = 2, // Interleaved RGB with 16 bits per channel
} nvtiffOutputFormat_t;
nvtiffOutputFormat_t is used to specify the decode output format.
Decoder Handle¶
struct nvtiffDecoder;
typedef struct nvtiffDecoder* nvtiffDecoder_t;
nvtiffDecoder_t stores intermediate decode buffers used in decoding.
Bitstream/File Handle¶
struct nvtiffStream;
typedef struct nvtiffStream* nvtiffStream_t;
nvtiffStream_t is used for parsing a tiff file. Tiff metadata can be extracted using APIs defined in Parser API Reference.
Decode Parameters Handle¶
struct nvtiffDecodeParams;
typedef struct nvtiffDecodeParams* nvtiffDecodeParams_t;
nvtiffDecodeParams_t is used to specify decode output parameters such as region of interest to decode, output format.
API Reference¶
Helper API Reference¶
nvtiffStreamCreate()¶
Creates an instance of the bitstream handle.
Signature:
nvtiffStatus_t nvtiffStreamCreate(nvtiffStream_t *tiff_stream);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t *tiff_stream |
Input/Output |
Host |
nvtiff bitstream handle |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffStreamDestroy()¶
Releases the bitstream handle.
Signature:
nvtiffStatus_t nvtiffStreamDestroy(nvtiffStream_t stream_handle);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t stream_handle |
Input |
Host |
nvtiff bitstream handle |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffDecoderCreateSimple()¶
Creates an instance of the decoder handle with default memory allocators.
Signature:
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffDecoder_t *decoder |
Input/Output |
Host |
nvtiff decoder handle |
cudaStream_t cuda_stream |
Input |
Host |
Used for asynchronous CUDA API calls |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffDecoderCreate¶
Creates an instance of the decoder handle.
Signature:
nvtiffStatus_t nvtiffDecoderCreate(nvtiffDecoder_t *decoder,
nvtiffDeviceAllocator_t *device_allocator,
nvtiffPinnedAllocator_t *pinned_allocator,
cudaStream_t cuda_stream);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffDecoder_t *decoder |
Input/Output |
Host |
nvtiff decoder handle |
nvtiffDeviceAllocator_t *device_allocator |
Input |
Host |
User provided device memory allocator. If set to NULL, the library will fallback to cudaMalloc/cudaFree. |
nvtiffPinnedAllocator_t *pinned_allocator |
Input |
Host |
User provided pinned memory allocator. If set to NULL, the library will fallback to cudaHostAlloc/cudaFreeHost. |
cudaStream_t cuda_stream |
Input |
Host |
Used for asynchronous CUDA API calls |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffDecoderDestroy()¶
Releases the decoder handle.
Signature:
nvtiffStatus_t nvtiffDecoderDestroy(nvtiffDecoder_t decoder,
cudaStream_t cuda_stream);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffDecoder_t decoder |
Input |
Host |
nvtiff decoder handle |
cudaStream_t cuda_stream |
Input |
Host |
Used for asynchronous CUDA API calls |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffDecodeParamsCreate()¶
Creates an instance of the decode output parameters handle.
Signature:
nvtiffStatus_t nvtiffDecodeParamsCreate(nvtiffDecodeParams_t *decode_params);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffDecodeParams_t *decode_params |
Input/Output |
Host |
Decode output parameters handle |
Returns:
nvtiffStatus_t - An error code as specified in nvtiffapireturncodes-label
nvtiffDecodeParamsDestroy()¶
Releases the decode output parameters handle.
Signature:
nvtiffStatus_t nvtiffDecodeParamsDestroy(nvtiffDecodeParams_t decode_params);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffDecodeParams_t decode_params |
Input |
Host |
Decode output parameters handle |
Returns:
nvtiffStatus_t - An error code as specified in nvtiffapireturncodes-label
Parser API Reference¶
The APIs in this section are used to parse a TIFF file and retrieve meta data. Meta data such as image dimensions, samples per pixel may be used to allocate output buffers on device memory.
nvtiffStreamParseFromFile()¶
Parses the TIFF file and stores the meta data in nvtiffStream_t .
Signature:
nvtiffStatus_t nvtiffStreamParseFromFile(const char *fname,
nvtiffStream_t tiff_stream)
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
const char *fname |
Input |
Host |
tiff file name on disk |
nvtiffStream_t tiff_stream |
Input/Output |
Host |
tiff stream handle |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffStreamParse()¶
Parses a tiff file which is loaded to host memory and stores the meta data in nvtiffStream_t.
Signature:
nvtiffStatus_t nvtiffStreamParse(const uint8_t *buffer,
size_t buffer_size,
nvtiffStream_t tiff_stream);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
const uint8_t *buffer |
Input |
Host |
Buffer containing tiff file |
size_t buffer_size |
Input |
Host |
tiff file size |
nvtiffStream_t tiff_stream |
Input/Output |
Host |
tiff stream handle |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffStreamPrint()¶
Prints to standard output, the TIFF file meta data stored in nvtiffStream_t.
Signature:
nvtiffStatus_t nvtiffStreamPrint(nvtiffStream_t tiff_stream)
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
tiff stream handle |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffStreamGetFileInfo()¶
Retrieves the image information defined in TIFF File Information.
Signature:
nvtiffStatus_t nvtiffStreamGetFileInfo(nvtiffStream_t tiff_stream,
nvtiffFileInfo_t *file_info)
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
tiff stream handle |
nvtiffFileInfo_t *file_info |
Input/Output |
Host |
pointer to nvtiffFileInfo_t |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffStreamGetNumImages()¶
Retrieves the number of images stored in a TIFF file.
Signature:
nvtiffStatus_t nvtiffStreamGetNumImages(nvtiffStream_t tiff_stream,
uint32_t *num_images)
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
tiff stream handle |
uint32_t *num_images |
Output |
Host |
Pointer to buffer containing number of images |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffStreamGetImageInfo()¶
Retrieves the image information of a given image stored in a TIFF file. Refer to TIFF Image Information for details on what information is retrieved.
Signature:
nvtiffStatus_t nvtiffStreamGetImageInfo(nvtiffStream_t tiff_stream,
uint32_t image_id,
nvtiffImageInfo_t *image_info)
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
tiff stream handle |
uint32_t image_id |
Input |
Host |
Image index |
nvtiffImageInfo_t *image_info |
Output |
Host |
Pointer to nvtiffImageInfo_t |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffStreamGetImageGeometry()¶
Retrieves image geometry related information. Geometry includes information whether the images use strips or tiles and their corresponding dimensions.
Signature:
nvtiffStatus_t nvtiffStreamGetImageGeometry(nvtiffStream_t tiff_stream,
uint32_t image_id,
nvtiffImageGeometry_t* geometry);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
tiff stream handle |
uint32_t image_id |
Input |
Host |
Image index |
nvtiffImageGeometry_t* geometry |
Input/Output |
Host |
Pointer to nvtiffImageGeometry_t |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffStreamGetGeoKeyInfo()¶
Retrieves the information about a geo key defined in GeoTIFF Keys. This information is useful in retrieving the values associated with the geo key.
Signature:
nvtiffStatus_t nvtiffStreamGetGeoKeyInfo(nvtiffStream_t tiff_stream,
nvtiffGeoKey_t key,
uint32_t *size,
uint32_t *count,
nvtiffGeoKeyDataType_t* type)
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
tiff stream handle |
nvtiffGeoKey_t key |
Input |
Host |
GeoTIFF key |
uint32_t *size |
Output |
Host |
Pointer to size of each value (in bytes) stored in key |
uint32_t *count |
Output |
Host |
Pointer to number of values stored in key |
nvtiffGeoKeyDataType_t *type |
Output |
Host |
Pointer to datatype of values stored in key |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffStreamGetNumberOfGeoKeys()¶
Retrieves the list of geokeys present in a TIFF file and their count. This information is later useful in retrieving the values associated with each geo key.
Signature:
nvtiffStatus_t nvtiffStreamGetNumberOfGeoKeys(nvtiffStream_t tiff_stream,
nvtiffGeoKey_t* key,
uint32_t *num_keys)
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
tiff stream handle |
nvtiffGeoKey_t *key |
Output |
Host |
Pointer to user allocated buffer for storing all geokeys in TIFF file (can be |
uint32_t *num_keys |
Output |
Host |
Pointer to number of geokeys stored in TIFF file |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffStreamGetTagInfo()¶
Retrieves the information about a TIFF tag defined in TIFF Tags. This information is later useful in retrieving the values associated with the TIFF tag.
Signature:
nvtiffStatus_t nvtiffStreamGetTagInfo(nvtiffStream_t tiff_stream,
uint32_t image_id,
nvtiffTag_t tiff_tag,
nvtiffTagDataType_t *tag_type,
uint32_t *size,
uint32_t *count);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
tiff stream handle |
uint32_t image_id |
Input |
Host |
image index |
nvtiffTag_t tiff_tag |
Input |
Host |
tiff tag |
nvtiffTagDataType_t *tag_type, |
Output |
Host |
Pointer to buffer containing the datatype of |
uint32_t *size |
Output |
Host |
Pointer to buffer containing size of individual values in |
uint32_t *count |
Output |
Host |
Pointer to buffer containing number of values in |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffStreamGetTagValue()¶
Retrieves the values stored in a TIFF tag.
Signature:
nvtiffStatus_t nvtiffStreamGetTagValue(nvtiffStream_t tiff_stream,
uint32_t image_id,
nvtiffTag_t tiff_tag,
void *tag_value,
uint32_t count);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
tiff stream handle |
uint32_t image_id |
Input |
Host |
image index |
nvtiffTag_t tiff_tag |
Input |
Host |
tiff tag |
void *tag_value |
Output |
Host |
Pointer to buffer containing values associated with |
uint32_t *count |
Output |
Host |
Pointer to buffer containing number of values in |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffStreamGetGeoKey()¶
Retrieves the values associated with a given geo key stored in a TIFF file.
Signature:
nvtiffStatus_t nvtiffStreamGetGeoKey(nvtiffStream_t tiff_stream,
nvtiffGeoKey_t key,
void *val,
uint32_t count);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
tiff stream handle |
nvtiffGeoKey_t key |
Input |
Host |
geo key for which information is retrieved |
void *val |
Output |
Host |
Pointer to user allocated buffer for storing values associated with |
uint32_t count |
Input |
Host |
Number of values copied (for geo key of type |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffStreamGetGeoKeyASCII()¶
Retrieves the values associated with geo key having ASCII values.
Signature:
nvtiffStatus_t NVTIFFAPI nvtiffStreamGetGeoKeyASCII(nvtiffStream_t tiff_stream,
nvtiffGeoKey_t key,
char* szStr,
uint32_t szStrMaxLen)
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
tiff stream handle |
nvtiffGeoKey_t key |
Input |
Host |
geo key for which information is retrieved |
char *szStr |
Output |
Host |
Pointer to user allocated buffer containing key values |
uint32_t szStrMaxLen |
Input |
Host |
Size of the user allocated buffer |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffStreamGetGeoKeySHORT()¶
Retrieves the values associated with geo key having SHORT values.
Signature:
nvtiffStatus_t NVTIFFAPI nvtiffStreamGetGeoKeySHORT(nvtiffStream_t tiff_stream,
nvtiffGeoKey_t key,
unsigned short *val,
uint32_t index,
uint32_t count)
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
tiff stream handle |
nvtiffGeoKey_t key |
Input |
Host |
geo key for which information is retrieved |
unsigned short *val |
Output |
Host |
Pointer to user allocated buffer containing key values |
uint32_t count |
Input |
Host |
Number of values which are required to be copied to |
uint32_t index |
Input |
Host |
Index of the starting value to be copied to |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffStreamGetGeoKeyDOUBLE()¶
Retrieves the values associated with geo key having DOUBLE values.
Signature:
nvtiffStatus_t NVTIFFAPI nvtiffStreamGetGeoKeyDOUBLE(nvtiffStream_t tiff_stream,
nvtiffGeoKey_t key,
double *val,
uint32_t index,
uint32_t count)
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
tiff stream handle |
nvtiffGeoKey_t key |
Input |
Host |
geo key for which information is retrieved |
double *val |
Output |
Host |
Pointer to user allocated buffer containing key values |
uint32_t count |
Input |
Host |
Number of values which are required to be copied to |
uint32_t index |
Input |
Host |
Index of the starting value to be copied to |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
Decode API Reference¶
nvtiffDecode()¶
Decodes image data on the GPU which is specified in tiff_stream.
Each image in the TIFF file is copied into the respective buffer pointed to by “imageOut_d”. This function is fully asynchronous.
When the photometric interpretation of an image is NVTIFF_PHOTOMETRIC_PALETTE or NVTIFF_PHOTOMETRIC_YCBCR, the decode output will be converted to RGB.
For images with multiple samples, the decode output will always be in planar contiguous format.
Signature:
nvtiffStatus_t nvtiffDecode(nvtiffStream_t tiff_stream,
nvtiffDecoder_t nvtiff_decoder,
unsigned char **image_out,
cudaStream_t cuda_stream);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
|
nvtiffDecoder_t nvtiff_decoder |
Input |
Host |
Decoder handle |
unsigned char **imageOut_d |
Output |
Host |
Host array (of size num_images in the TIFF file) of pointers to device buffers.Each device buffer should have a size of image_width * image height * bitdepth * samples_per_pixel When the photometric interpretation for an image is palette mode, the device buffer should have a size of image_width * image height * 3 * 2 |
cudaStream_t cuda_stream |
Input |
Host |
|
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffDecodeRange()¶
This function is similar to nvtiffDecode(). It allows the user to specify a range of images to be decoded
(instead of decoding all images in the file).
When the photometric interpretation of an image is NVTIFF_PHOTOMETRIC_PALETTE or NVTIFF_PHOTOMETRIC_YCBCR, the decode output will be converted to RGB.
For images with multiple samples, the decode output will always be in planar contiguous format.
Signature:
nvtiffStatus_t NVTIFFAPI nvtiffDecodeRange(nvtiffStream_t tiff_stream,
nvtiffDecoder_t decoder,
unsigned int sub_file_start,
unsigned int sub_file_num,
unsigned char **image_out,
cudaStream_t cuda_stream);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
|
nvtiffDecoder_t nvtiff_decoder |
Input |
Host |
Decoder handle |
unsigned int sub_file_start |
Input |
Host |
Index of the first image to decode, in [0, tiff_info.num_sub_files). |
unsigned int sub_file_num |
Input |
Host |
Number of images to decode starting from |
unsigned char **imageOut_d |
Output |
Host |
Host array (of size num_images in the TIFF file) of pointers to device buffers.Each device buffer should have a size of image_width * image height * bitdepth * samples_per_pixel When the photometric interpretation for an image is palette mode, the device buffer should have a size of image_width * image height * 3 * 2 |
cudaStream_t cuda_stream |
Input |
Host |
|
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffDecodeImage()¶
Decodes a single image on the GPU which is specified in tiff_stream. The function is asynchronous with respect to the host.
Additional control of the decode output is possible using an instance nvtiffDecodeParams_t.
Signature:
nvtiffStatus_t nvtiffDecodeImage(nvtiffStream_t tiff_stream,
nvtiffDecoder_t decoder,
nvtiffDecodeParams_t params,
uint32_t image_id,
void* image_out_d,
cudaStream_t cuda_stream);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
|
nvtiffDecoder_t nvtiff_decoder |
Input |
Host |
Decoder handle |
nvtiffDecodeParams_t params |
Input |
Host |
Used to control the decoded output (like specifying ROI, output format). |
uint32_t image_id |
Input |
Host |
Corresponds to the image index(IFDs) within a multi images TIFF file. Cannot exceed the total number of images in a TIFF file. |
void* image_out_d |
Output |
Device |
Decode output buffer. For allocation size, see nvtiffDecodeParamsSetOutputFormat() |
cudaStream_t cuda_stream |
Input |
Host |
|
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffDecodeCheckSupported()¶
Helps determine whether any given image within a tiff file specified by tiff_stream can be decoded by nvTIFF.
Returns NVTIFF_STATUS_SUCCESS, if the image is supported
Signature:
nvtiffStatus_t nvtiffDecodeCheckSupported(nvtiffStream_t tiff_stream,
nvtiffDecoder_t decoder,
nvtiffDecodeParams_t params,
uint32_t image_id);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffStream_t tiff_stream |
Input |
Host |
|
nvtiffDecoder_t nvtiff_decoder |
Input |
Host |
Decoder handle |
nvtiffDecodeParams_t params |
Input |
Host |
Used to control the decoded output (like specifying ROI, output format). |
uint32_t image_id |
Input |
Host |
Corresponds to the image index(IFDs) within a multi images TIFF file. Cannot exceed the total number of images in a TIFF file. |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
Decode Parameters API Reference¶
The APIs under this category are used to initialize the decoding parameters as part of the nvtiffDecodeParams_t handle.
Once initialized, the handle can be passed as an input to nvtiffDecodeImage()
nvtiffDecodeParamsSetOutputFormat()¶
Used to set the decode output format. See Decode Output Format for details. The default value is NVTIFF_OUTPUT_UNCHANGED_I.
Note
When the photometric interpretation is NVTIFF_PHOTOMETRIC_YCBCR and compression is NVTIFF_COMPRESSION_JPEG, output format must be set to either NVTIFF_OUTPUT_RGB_I_UINT8 or NVTIFF_OUTPUT_RGB_I_UINT16.
Note
When the photometric interpretation is NVTIFF_PHOTOMETRIC_MASK, only NVTIFF_OUTPUT_UNCHANGED_I can be used.
When setting the output format to NVTIFF_OUTPUT_UNCHANGED_I-
the size in bytes of the decode output buffer when bits_per_pixel is a multiple 8, should be
image_width * image_height * (bits_per_pixel/8)
the size in bytes of the decode output buffer when bits_per_pixel is less than 8, should be
(image_width * bits_per_pixel + 7)/8 * image_height
When setting the output to NVTIFF_OUTPUT_RGB_I_UINT8-
the size in bytes of the decode output buffer should be
image_width * image_height * 3 * sizeof(uint8_t)
When setting the output to NVTIFF_OUTPUT_RGB_I_UINT16-
the size in bytes of the decode output buffer should be
image_width * image_height * 3 * sizeof(uint16_t)
Signature:
nvtiffStatus_t nvtiffDecodeParamsSetOutputFormat(nvtiffDecodeParams_t decode_params,
nvtiffOutputFormat_t format);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffDecodeParams_t decode_params |
Input/Output |
Host |
Decode output parameters handle. |
nvtiffOutputFormat_t format |
Input |
Host |
Output format value. Defaults to |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
nvtiffDecodeParamsSetROI()¶
Used to set the region of interest for decoding. The entire image is decoded by default.
offset_x and offset_y should be greater than or equal to 0, and cannot exceed image width and height respectively.
offset_x + roi_width and offset_y + roi_height cannot exceed image width and image height respectively.
When image bitdepth is 1, offset_x and roi_width should be a multiple of 8
Signature:
nvjpeg2kStatus_t nvtiffDecodeParamsSetROI(nvtiffDecodeParams_t decode_params,
int32_t offset_x,
int32_t offset_y,
int32_t roi_width,
int32_t roi_height)
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvtiffDecodeParams_t decode_params |
Input/Output |
Host |
Decode output parameter handle |
int32_t offset_x |
Input |
Host |
Image offset along the horizontal direction relative to the top left corner. |
int32_t offset_y |
Input |
Host |
Image offset along the vertical direction relative to the top left corner. |
int32_t roi_width |
Input |
Host |
Image width relative to offset_x |
int32_t roi_height |
Input |
Host |
Image height relative to offset_y |
Returns:
nvtiffStatus_t - An error code as specified in Decode API Return Status Codes
Encode API Reference¶
nvTiffEncodeCtxCreate()¶
This function encoding context based on the specified parameters that can be used to perform a parallel LZW compression of images.
Signature:
nvTiffEncodeCtx_t nvTiffEncodeCtxCreate(int dev,
unsigned int imagesMax,
unsigned int stripsPerImageMax,
size_t memLimit=0);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
int dev |
Input |
Device to use for CUDA calls and kernel launches |
|
unsigned int imagesMax |
Input |
maximum number of images that will be encoded using the returned context |
|
unsigned int stripsPerImageMax |
Input |
maximum number of strips that the images that will be encoded using the returned context will be partitioned into |
|
size_t memLimit |
Input |
maximum amount of device memory that can be used to allocate the internal buffers required by the strip compression kernel |
Returns:
SUCCESS - on success returns a pointer to nvTiffEncodeCtx_t
NULL - otherwise.
nvTiffEncodeCtxDestroy()¶
Destroys context ctx freeing all the allocated memory on both the host and the device.
Signature:
void nvTiffEncodeCtxDestroy(nvTiffEncodeCtx_t *ctx);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvTiffEncodeCtx_t *ctx |
Input |
Destroys context ctx freeing all the allocated memory on both the host and the device. |
nvTiffEncode()¶
Perform the encoding of multiple images using the resources specified by the encoding context. Each image is divided into strips formed by groups of consecutive rows and then each strip is compressed using LZW independently.
This function is fully asynchronous.
Signature:
int NVTIFFAPI nvTiffEncode(nvTiffEncodeCtx_t *ctx,
unsigned int nrow,
unsigned int ncol,
unsigned int pixelSize,
unsigned int rowsPerStrip,
unsigned int nImages,
unsigned char **images_d,
unsigned long long stripAllocSize,
unsigned long long *stripSize_d,
unsigned long long *stripOffs_d,
unsigned char *stripData_d,
cudaStream_t stream=0);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvTiffEncodeCtx_t *ctx |
Input |
the nvTiffEncodeCtx_t returned by nvTiffEncodeCtxCreate(); |
|
unsigned int nrow |
Input |
number of rows of the images to compress; |
|
unsigned int ncol |
Input |
number of columns of the images to compress; |
|
unsigned int pixelSize |
Input |
pixel size, in bytes, for the images to compress; |
|
unsigned int rowsPerStrip |
Input |
number of rows to be compressed together in a single strip; |
|
unsigned int nImages |
Input |
number of images to compress; |
|
unsigned char **images_d |
Input |
Host |
host array of size nImages of pointers to device buffers |
unsigned long long stripAllocSize |
Input |
the estimated maximum size for compressed strips; |
|
unsigned int *stripSize_d |
Output |
Device |
device array of size at least ceil(nrow/rowsPerStrip)*nImages |
unsigned int *stripOffs_d |
Output |
Device |
device array of size at least ceil(nrow/rowsPerStrip)*nImages |
unsigned long long *stripData_d |
Output |
Device |
device array of size at least ceil(nrow/rowsPerStrip)*nImages*stripAllocSize in which the compressed strips are returned |
stream |
Input |
the stream to use for the kernel launches |
Returns:
NVTIFF_ENCODE_SUCCESS - on success, the compressed strips can be accessed after the subsequent call to nvTiffEncodeFinalize(), see below;
NVTIFF_ENCODE_INVALID_CTX - ctx is invalid.
NVTIFF_ENCODE_INVALID_STRIP_NUM - if the specified nrow, rowsPerStrip and nImages amount to a number of strips to be compressed greater than those specified by the parameters imagesMax and stripsPerImageMax
specified at the creation of the context ctx;
CUTIFF_ENCODE_INVALID_IMAGE_NUM: if the specified nImages is greater than the parameter imagesMax specified at the creation of the context ctx;
nvTiffEncodeFinalize()¶
This function completes the compression process initiated by nvTiffEncode(). Since nvTiffEncode() is asynchronous, the state about its runtime operations is checked via this finalization call. Please note that this function is NOT fully asynchronous. On entry, it synchronizes on the stream specified as a parameter and, if the all the operations initiated by the previous cuTiffEncode() call terminated with success, then it launches a kernel, asynchronously, to finalize the data arrays passed to cuTiffEncode() (stripSize_d, stripOffs_d and stripData_d). Because of that, before accessing those arrays it is necessary to synchronize on the passed stream.
Signature:
int nvTiffEncodeFinalize(nvTiffEncodeCtx_t *ctx,
cudaStream_t stream=0);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
nvTiffEncodeCtx_t *ctx |
Input |
the nvTiffEncodeCtx_t passed to nvTiffEncode(); |
|
stream |
Input |
the stream to use for the kernel launches |
Returns:
NVTIFF_ENCODE_SUCCESS - on success; the strips sizes, offsets and data can be accessed in the array stripSize_d,
stripOffs_d, stripData_d passed to nvTiffEncode() after all the operations enqueued on stream are concluded;
NVTIFF_ENCODE_INVALID_CTX - ctx is invalid.
NVTIFF_ENCODE_COMP_STRIP_TOO_LONG - currently the compression procedure supports strips with a compressed size up to 48KB;
if one strip would be compressed into a larger size then this error is returned
NVTIFF_ENCODE_COMP_OVERFLOW - this error is returned in case one or more strips compress to a size grater than the value of the
parameter stripAllocSize passed to nvTiffEncode()
nvTiffWriteFile()¶
This is a convenience function to write compressed images to a single TIFF file. Library users may want to implement their own function to use additional/custom TIFF tags.
Signature:
int nvTiffWriteFile(const char *fname,
int tiffVer,
unsigned int nImages,
unsigned int nrow,
unsigned int ncol,
unsigned int rowsPerStrip,
unsigned short samplesPerPixel,
unsigned short *bitsPerSample,
unsigned int photometricInt,
unsigned int planarConf,
unsigned long long *stripSize,
unsigned long long *stripOffs,
unsigned char *stripData);
Parameters:
Parameter |
Input/Output |
Memory |
Description |
|---|---|---|---|
const char *fname |
Input |
Host |
the name of the output TIFF file; |
int tiffVer |
Input |
specifies whether to use regular Tiff or a BigTiff file format; for regular Tiff use VER_REG_TIFF; for BigTiff use VER_BIG_TIFF; |
|
unsigned int nImages |
Input |
number of images to write into the file |
|
unsigned int nrow |
Input |
number of rows of every image |
|
unsigned int ncol |
Input |
number of columns of every image; |
|
unsigned int rowsPerStrip |
Input |
number of rows that form a Tiff strip |
|
unsigned short samplesPerPixel |
Input |
number of components per pixel |
|
unsigned short bitsPerSample |
Input |
array of length samplesPerPixel specifying the number of bits per component; |
|
unsigned int photometricInt |
Input |
color space of the image data; supported values: 1 or 2; |
|
unsigned int planarConf |
Input |
how the components of each pixel are stored; supported values: 1 (chunky format); |
|
unsigned long long *stripSize |
Input |
Host |
host array of size ceil(nrow/rowsPerStrip)*nImages containing the length of the compressed strips; |
unsigned long long *stripOffs |
Input |
Host |
host array of size ceil(nrow/rowsPerStrip)*nImages containing the starting offset of the compressed strips inside the stripData buffer; |
unsigned char *stripData |
Input |
Host |
host array containing the ceil(nrow/rowsPerStrip)*nImages compressed strips; strips are expected to be stored one after the other starting from the first image to the last, from the top to bottom; |
Returns:
NVTIFF_WRITE_SUCCESS - on success
NVTIFF_WRITE_UNSUPP_PLANAR_CONF - if the value of planarConf parameter is not equal to 1;.
NVTIFF_WRITE_UNSUPP_PHOTOMETRIC_INT - if the value of photometricInt parameter is neither 1 nor 2;