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
Samples per pixel
Up to 8 samples per pixel in Planar Contiguous mode
Up to 4 samples per pixel in Planar Separate mode
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/CentOS |
9.1 |
5.14 |
11.3.1 |
2.34 |
8.3 |
4.18 |
8.5.0 |
2.28 |
||
7.9 |
3.10.0 |
6 |
2.17 |
||
Ubuntu |
22.04 |
5.15.0 |
11.2.0 |
2.34 |
|
20.04 |
5.13.0 |
9.3.0 |
2.31 |
||
OpenSUSE Leap |
15.4 |
5.14.21 |
7.5.0 |
2.31 |
|
SUSE SLES |
15.4 |
5.14.21 |
7.5.0 |
2.31 |
|
Debian |
11.6 |
5.10.0 |
10.2.1 |
2.31 |
|
10.13 |
4.19.0 |
8.3.0 |
2.28 |
||
Fedora |
37 |
6.07 |
12.2.1 |
2.36 |
|
Windows versions:
Windows 10 and Windows Server 2019
WSL
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.
Python Tiff Decode example¶
Prerequisites¶
Python packages
cupy
$ pip install cupy
numpy
$ pip install numpy
tifffile
$ pip install tifffile
imagecodecs
$ pip install imagecodecs
Install nvTIFF Python Wheel¶
$ pip install nvtiff-0.1.0-cp36-cp36m-linux_x86_64.whl
Usage:¶
$ python3 nvtiff_test.py -h
usage: nvtiff_test.py [-h] [-o OUTPUT_FILE_PREFIX] [-s] [-c] [-p]
[-r SUBFILE_RANGE]
tiff_file
positional arguments:
tiff_file tiff file to decode.
optional arguments:
-h, --help show this help message and exit
-o OUTPUT_FILE_PREFIX, --output_file_prefix OUTPUT_FILE_PREFIX
Output file prefix to save decoded data. Will save one
file per image in tiff file.
-s, --return_single_array
Return single array from nvTiff instead of list of
arrays
-c, --check_output Compare nvTiff output to reference CPU result
-p, --use_pinned_mem Read TIFF data from pinned memory.
-r SUBFILE_RANGE, --subfile_range SUBFILE_RANGE
comma separated list of starting and ending file
indices to decode, inclusive
Python Example¶
$ python3 nvtiff_test.py bali_notiles.tif
Command line arguments:
tiff_file: bali_notiles.tif
return_single_array: False
output_file_prefix: None
check_output: False
use_pinned_mem: False
subfile_range: None
Time for tifffile:
decode: 0.010347366333007812 s
h2d copy: 0.0010058879852294922 s
total: 0.011353254318237305 s
Time for nvTiff:
open: 0.002551555633544922 s
decode: 0.0005545616149902344 s
total: 0.0031061172485351562 s
Type Declarations¶
nvTIFF Decode API Return Status Codes¶
The return codes of the nvTIFF Decode APIs are listed below:
#define NVTIFF_DECODE_SUCCESS (0)
#define NVTIFF_DECODE_INVALID_CTX (1)
#define NVTIFF_DECODE_INVALID_RANGE (2)
Description of the Return Codes
Return Code |
Description |
|---|---|
NVTIFF_DECODE_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_DECODE_INVALID_CTX (1) |
Invalid CTX. |
NVTIFF_DECODE_INVALID_RANGE (2) |
Range of subfiles not valid |
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 V2 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;
nvtiffPhotometricInt_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.
Decoder Handle¶
struct nvtiffDecoder;
typedef struct nvtiffDecoder* nvtiffDecoder_t;
The nvtiffDecoder_t handle stores intermediate decode buffers used in decoding.
Bitstream/File Handle¶
struct nvtiffStream;
typedef struct nvtiffStream* nvtiffStream_t;
This handle is used for parsing a tiff file. Tiff metadata can be extracted using APIs defined in Parser API Reference.
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
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
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
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
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;