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 `nullptr`, in which case only `num_keys` is returned)
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 `tiff_tag`. See nvtifftagdatatype-label for which datatypes are supported.
uint32_t *size	Output	Host	Pointer to buffer containing size of individual values in `tiff_tag`
uint32_t *count	Output	Host	Pointer to buffer containing number of values in `tiff_tag`

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 `tiff_tag`
uint32_t *count	Output	Host	Pointer to buffer containing number of values in `tiff_tag`

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 `key`
uint32_t count	Input	Host	Number of values copied (for geo key of type `NVTIFF_GEOKEY_TYPE_ASCII`, this is ignored. For geo key of type `NVTIFF_GEOKEY_TYPE_SHORT`, `count=1` is implied)

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 `szStr`

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 `val`
uint32_t index	Input	Host	Index of the starting value to be copied to `val`

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 `val`
uint32_t index	Input	Host	Index of the starting value to be copied to `val`

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	`tiff_stream` handle in which the TIFF file has been read.
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	`cuda_stream` where all the GPU work will be submitted

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	`tiff_stream` handle in which the TIFF file has been read.
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 `sub_file_start`, in (0, tiff_info.num_sub_files]
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	`cuda_stream` where all the GPU work will be submitted

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	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)nImagesstripAllocSize 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;