nvTiff 文档¶
简介¶
nvTIFF 是一个基于 CUDA 平台构建的 GPU 加速 TIFF（标签图像文件格式）编码/解码库。该库在 Volta+ GPU 架构上受支持。它支持以下 TIFF 功能集
注意
在本文档中，“CPU”和“主机”术语可以互换使用。同样，“GPU”和“设备”术语也可以互换使用。
解码器¶
平面分离和连续模式
每个像素最多 16 个样本
压缩
JPEG（通过 nvJPEG）
Deflate（通过 nvCOMP）
LZW
无（未压缩）
颜色空间可以是 - 灰度、RGB、YCbCr、RGB 调色板。当压缩数据处于 YCbCr 或调色板模式时，库会将解码后的输出转换为 RGB 色彩空间。
TIFF 文件可以使用瓦片或条带。
当压缩类型为：无、Deflate、LZW 时，每个样本最多 32 位。当压缩类型为 JPEG 时，每个样本最多 8 位。
具有不同属性的多个图像的 TIFF 文件。
用于检索 GeoTIFF 元数据的 API
下图表示 nvTIFF 解码器与其他 CUDA 库（如 nvJPEG 和 nvCOMP（用于 DEFLATE 解压缩））的交互。用户应用程序将在调用 nvTIFF 解码器之前调用 CUDA API 以创建解码输出缓冲区。
nvTiff 解码器概述¶
编码器¶
仅平面连续模式。
每个像素最多 4 个样本。
LZW 压缩。
压缩数据以条带形式组织。
每个样本最多 32 位。
TIFF 文件中的多个图像。要压缩的所有图像必须具有相同的属性。
nvTiff 编码器概述¶
将 GPU 加速应用于 TIFF 文件¶
一个 TIFF 文件可能包含单个或多个图像。这些图像中的每一个都细分为条带或瓦片。每个条带/瓦片都可以并行编码/解码，从而提供比 CPU 实现更快的速度。
当解码具有相同元数据的多个图像的 TIFF 文件时，所有图像的条带/瓦片可以作为单个批处理 CUDA 内核的一部分进行解码。编码的情况正好相反，每个条带/瓦片都可以并行压缩。压缩后的瓦片/条带可以拼接以创建 TIFF 文件
先决条件¶
CUDA 工具包版本 11.0 及以上。
CUDA 驱动程序版本 r450 及以上。
nvCOMP 2.6+（当压缩为 deflate 时需要）。
支持的平台¶
Linux 版本
架构 |
发行版信息 |
||||
|---|---|---|---|---|---|
名称 |
版本 |
内核 |
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 版本
Windows 10、Windows 11 和 Windows Server 2023
WSL
Tegra
在 Jetpack v5.1.3 及以上版本上受支持。
安装 nvTIFF¶
NVIDIA DevZone¶
nvTIFF 二进制文件和下载说明可在此处获取 - https://developer.nvidia.com/nvtiff-downloads。
对于 Linux，二进制文件以存档 (.tar.xz) 和软件包管理器格式 (.deb, .rpm) 提供
对于 Windows，二进制文件以存档 (.zip) 和 Windows 安装程序格式提供。
PyPi¶
nvTIFF 二进制文件在 PyPi 上可用，可以通过 pip 使用以下命令安装。这使得该库可以轻松地在 python 环境中使用。
要为 CUDA 12.x 安装 nvTIFF
python3 -m pip install nvidia-nvtiff-cu12
要在 Tegra 平台上为 CUDA 12.x 安装 nvTIFF
python3 -m pip install nvidia-nvtiff-tegra-cu12
要为 CUDA 11.x 安装 nvTIFF
python3 -m pip install nvidia-nvtiff-cu11
要在 Tegra 平台上为 CUDA 11.x 安装 nvTIFF
python3 -m pip install nvidia-nvtiff-tegra-cu11
快速入门指南¶
本节将介绍如何在几个快速步骤中使用解码器和编码器 API。API 详细信息将在下一节中介绍。
注意
nvTIFF 示例链接： https://github.com/NVIDIA/CUDALibrarySamples/tree/master/nvTIFF
请注意，由于 TIFF 图像的解码和编码是两个根本不同的问题，因此解码和编码的 API 也是不同且独立的。
nvTIFF 解码¶
该库从磁盘读取文件并将图像数据加载到设备内存。
创建以下实例 -
nvtiffStream_t - 用于解析比特流并存储比特流元数据
nvtiffDecoder_t - 用于存储解码所需的工作缓冲区
nvtiffStream_t nvtiff_stream;
nvtiffDecoder_t nvtiff_decoder;
nvtiffStreamCreate(&nvtiff_stream);
nvtiffDecoderCreateSimple(&nvtiff_decoder);
使用 nvtiffStreamParseFromFile API 从磁盘解析 tiff 文件。
// 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
提取 tiff 文件元数据。
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 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));
}
调用 nvtiffDecode 函数以解码文件中的数据或数据范围。
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
转到步骤 1 以解码另一个图像。解码完所有图像后，通过调用相应的销毁 API 释放 nvTIFF 库资源。
nvTIFF 编码¶
初始化下面列出的库句柄和编码器参数
// 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);
调用 nvTiffEncode 函数进行编码。由于我们无法预先知道压缩条带的大小，因此我们首先尝试在根据我们的初始估计分配的缓冲区中进行编码。如果一个或多个条带需要的内存超过“encStripAllocSize”字节，那么我们需要使用更大的缓冲区重新启动编码过程。在这种情况下，在编码失败后，库会在上下文字段 stripSizeMax 中将编码成功所需的最小尺寸传递给用户。这样，编码过程只会因输出缓冲区太小而失败一次。成功编码后（nvTiffEncodeFinalize() 返回 NVTIFF_ENCODE_SUCCESS），压缩后的条带数据、偏移量和大小将在缓冲区 stripData_d、stripOffs_d 和 stripSize_d 中返回。此外，压缩条带数据的总大小也将在 ctx->stripSizeTot 中返回。请注意，在访问这些缓冲区之前，您需要在流
stream上同步。
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));
将压缩图像写入 TIFF 文件。
// 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 解码 / 编码演示示例¶
二进制文件 nvTiff_exmaple 提供了 nvTIFF 库的编码和解码功能的完整而详细的使用示例。
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.
类型声明¶
nvTIFF 编码 API 返回状态代码¶
下面列出了 nvTIFF 编码 API 的返回代码
#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)
返回代码的描述
返回代码 |
描述 |
|---|---|
NVTIFF_ENCODE_SUCCESS (0) |
API 调用已成功完成。请注意，许多调用是异步的，并且某些错误可能仅在同步后才会看到。 |
NVTIFF_ENCODE_INVALID_CTX (1) |
无效 CTX。 |
NVTIFF_ENCODE_INVALID_STRIP_NUM (2) |
无效的条带号 |
NVTIFF_ENCODE_COMP_OVERFLOW (3) |
压缩期间溢出 |
NVTIFF_ENCODE_COMP_STRIP_TOO_LONG (4) |
条带过长 |
nvTIFF 写入 API 返回状态代码¶
下面列出了 nvTIFF 写入 API 的返回代码
#define NVTIFF_WRITE_SUCCESS (0)
#define NVTIFF_WRITE_UNSUPP_PLANAR_CONF (1)
#define NVTIFF_WRITE_UNSUPP_PHOTOMETRIC_INT (2)
返回代码的描述
返回代码 |
描述 |
|---|---|
NVTIFF_WRITE_SUCCESS (0) |
API 调用已成功完成。请注意，许多调用是异步的，并且某些错误可能仅在同步后才会看到。 |
NVTIFF_WRITE_UNSUPP_PLANAR_CONF (1) |
如果 planarConf 参数的值不等于 1； |
NVTIFF_WRITE_UNSUPP_PHOTOMETRIC_INT (2) |
如果 photometricInt 参数的值既不是 1 也不是 2； |
解码 API 返回状态代码¶
下面列出了 nvTiff 解码 API 的返回代码
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;
返回代码的描述
返回代码 |
描述 |
|---|---|
NVTIFF_STATUS_SUCCESS (0) |
API 调用已成功完成。请注意，许多调用是异步的，并且某些错误可能仅在同步后才会看到。 |
NVTIFF_STATUS_NOT_INITIALIZED (1) |
库句柄未初始化。 |
NVTIFF_STATUS_INVALID_PARAMETER (2) |
传递了错误的参数。例如，作为输入数据的空指针，或无效的枚举值 |
NVTIFF_STATUS_BAD_TIFF (3) |
无法解析 TIFF 流。可能是由于无法处理的损坏 |
NVTIFF_STATUS_TIFF_NOT_SUPPORTED (4) |
尝试解码 nvTIFF 库不支持的 TIFF 流。 |
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 无法加载 nvcomp 库。 |
NVTIFF_STATUS_NVJPEG_NOT_FOUND (10) |
nvTiff 无法加载 nvjpeg 库。 |
NVTIFF_STATUS_TAG_NOT_FOUND (11) |
nvTiff 无法找到有关所提供标签的信息 |
NVTIFF_STATUS_PARAMETER_OUT_OF_BOUNDS (12) |
提供的参数超出可能值的范围 |
TIFF 标签数据类型¶
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 对应于 TIFF 标签的数据类型。
GeoTIFF 密钥¶
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 对应于 GeoTIFF 规范中列出的各种地理密钥。用户可以参考 GeoTIFF 规范以获取更多详细信息。
GeoTIFF 密钥数据类型¶
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 对应于地理密钥的数据类型。
设备分配器接口¶
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;
自定义设备分配器支持流顺序分配和用户定义的上下文信息 *device_ctx。当调用设备分配器时，nvTiff 将传递 *device_ctx 作为设备分配器的输入。
固定分配器接口¶
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;
自定义固定分配器支持流顺序分配和用户定义的上下文信息 *pinned_ctx。当调用固定分配器时，nvTiff 将传递 *pinned_ctx 作为固定分配器的输入。
图像类型¶
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 枚举对应于 TIFF 规范中定义的 NewSubfiletype (254) 标签。
压缩类型¶
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 枚举对应于 TIFF 规范中定义的 Compression (259) 标签。
光度解释¶
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 枚举对应于 TIFF 规范中定义的 PhotometricInterpretation (262) 标签。
平面配置¶
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 枚举对应于 TIFF 规范中定义的 PlanarConfiguration (284) 标签。
样本格式¶
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 枚举对应于 TIFF 规范中定义的 SampleFormat (339) 标签。
TIFF 文件信息¶
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 枚举用于检索一些 TIFF 文件元数据。此信息可用于分配解码输出缓冲区。
TIFF 图像信息¶
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 包含存储在 TIFF 文件中的图像的一些附加元数据。
TIFF 几何类型¶
typedef enum nvtiffImageGeometryType {
NVTIFF_IMAGE_STRIPED = 0,
NVTIFF_IMAGE_TILED = 1,
} nvtiffImageGeometryType_t;
nvtiffImageGeometryType_t 指定 tiff 文件是使用条带还是瓦片
TIFF 几何信息¶
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;
存储图像几何形状以及条带/瓦片尺寸。当几何类型为 NVTIFF_IMAGE_STRIPED 时，strile_width 等于图像宽度。
解码输出格式¶
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 用于指定解码输出格式。
解码器句柄¶
struct nvtiffDecoder;
typedef struct nvtiffDecoder* nvtiffDecoder_t;
nvtiffDecoder_t 存储解码中使用的中间解码缓冲区。
比特流/文件句柄¶
struct nvtiffStream;
typedef struct nvtiffStream* nvtiffStream_t;
nvtiffStream_t 用于解析 tiff 文件。可以使用 解析器 API 参考 中定义的 API 提取 Tiff 元数据。
解码参数句柄¶
struct nvtiffDecodeParams;
typedef struct nvtiffDecodeParams* nvtiffDecodeParams_t;
nvtiffDecodeParams_t 用于指定解码输出参数，例如要解码的感兴趣区域、输出格式。
API 参考¶
Helper API 参考¶
nvtiffStreamCreate()¶
创建比特流句柄的实例。
签名
nvtiffStatus_t nvtiffStreamCreate(nvtiffStream_t *tiff_stream);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t *tiff_stream |
输入/输出 |
主机 |
nvtiff 比特流句柄 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffStreamDestroy()¶
释放比特流句柄。
签名
nvtiffStatus_t nvtiffStreamDestroy(nvtiffStream_t stream_handle);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t stream_handle |
输入 |
主机 |
nvtiff 比特流句柄 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffDecoderCreateSimple()¶
使用默认内存分配器创建解码器句柄的实例。
签名
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffDecoder_t *decoder |
输入/输出 |
主机 |
nvtiff 解码器句柄 |
cudaStream_t cuda_stream |
输入 |
主机 |
用于异步 CUDA API 调用 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffDecoderCreate¶
创建解码器句柄的实例。
签名
nvtiffStatus_t nvtiffDecoderCreate(nvtiffDecoder_t *decoder,
nvtiffDeviceAllocator_t *device_allocator,
nvtiffPinnedAllocator_t *pinned_allocator,
cudaStream_t cuda_stream);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffDecoder_t *decoder |
输入/输出 |
主机 |
nvtiff 解码器句柄 |
nvtiffDeviceAllocator_t *device_allocator |
输入 |
主机 |
用户提供的设备内存分配器。如果设置为 NULL，库将回退到 cudaMalloc/cudaFree。 |
nvtiffPinnedAllocator_t *pinned_allocator |
输入 |
主机 |
用户提供的固定内存分配器。如果设置为 NULL，库将回退到 cudaHostAlloc/cudaFreeHost。 |
cudaStream_t cuda_stream |
输入 |
主机 |
用于异步 CUDA API 调用 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffDecoderDestroy()¶
释放解码器句柄。
签名
nvtiffStatus_t nvtiffDecoderDestroy(nvtiffDecoder_t decoder,
cudaStream_t cuda_stream);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffDecoder_t decoder |
输入 |
主机 |
nvtiff 解码器句柄 |
cudaStream_t cuda_stream |
输入 |
主机 |
用于异步 CUDA API 调用 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffDecodeParamsCreate()¶
创建解码输出参数句柄的实例。
签名
nvtiffStatus_t nvtiffDecodeParamsCreate(nvtiffDecodeParams_t *decode_params);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffDecodeParams_t *decode_params |
输入/输出 |
主机 |
解码输出参数句柄 |
返回值
nvtiffStatus_t - 错误代码，如 nvtiffapireturncodes-label 中指定
nvtiffDecodeParamsDestroy()¶
释放解码输出参数句柄。
签名
nvtiffStatus_t nvtiffDecodeParamsDestroy(nvtiffDecodeParams_t decode_params);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffDecodeParams_t decode_params |
输入 |
主机 |
解码输出参数句柄 |
返回值
nvtiffStatus_t - 错误代码，如 nvtiffapireturncodes-label 中指定
解析器 API 参考¶
本节中的 API 用于解析 TIFF 文件并检索元数据。图像尺寸、每个像素的样本数等元数据可用于在设备内存上分配输出缓冲区。
nvtiffStreamParseFromFile()¶
解析 TIFF 文件并将元数据存储在 nvtiffStream_t 中。
签名:
nvtiffStatus_t nvtiffStreamParseFromFile(const char *fname,
nvtiffStream_t tiff_stream)
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
const char *fname |
输入 |
主机 |
磁盘上的 tiff 文件名 |
nvtiffStream_t tiff_stream |
输入/输出 |
主机 |
tiff 流句柄 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffStreamParse()¶
解析加载到主机内存的 tiff 文件，并将元数据存储在 nvtiffStream_t 中。
签名:
nvtiffStatus_t nvtiffStreamParse(const uint8_t *buffer,
size_t buffer_size,
nvtiffStream_t tiff_stream);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
const uint8_t *buffer |
输入 |
主机 |
包含 tiff 文件的缓冲区 |
size_t buffer_size |
输入 |
主机 |
tiff 文件大小 |
nvtiffStream_t tiff_stream |
输入/输出 |
主机 |
tiff 流句柄 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffStreamPrint()¶
将存储在 nvtiffStream_t 中的 TIFF 文件元数据打印到标准输出。
签名:
nvtiffStatus_t nvtiffStreamPrint(nvtiffStream_t tiff_stream)
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
tiff 流句柄 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffStreamGetFileInfo()¶
检索 TIFF 文件信息 中定义的图像信息。
签名:
nvtiffStatus_t nvtiffStreamGetFileInfo(nvtiffStream_t tiff_stream,
nvtiffFileInfo_t *file_info)
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
tiff 流句柄 |
nvtiffFileInfo_t *file_info |
输入/输出 |
主机 |
指向 nvtiffFileInfo_t 的指针 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffStreamGetNumImages()¶
检索存储在 TIFF 文件中的图像数量。
签名:
nvtiffStatus_t nvtiffStreamGetNumImages(nvtiffStream_t tiff_stream,
uint32_t *num_images)
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
tiff 流句柄 |
uint32_t *num_images |
输出 |
主机 |
指向包含图像数量的缓冲区的指针 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffStreamGetImageInfo()¶
检索存储在 TIFF 文件中的给定图像的图像信息。有关检索哪些信息的详细信息，请参阅 TIFF 图像信息。
签名:
nvtiffStatus_t nvtiffStreamGetImageInfo(nvtiffStream_t tiff_stream,
uint32_t image_id,
nvtiffImageInfo_t *image_info)
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
tiff 流句柄 |
uint32_t image_id |
输入 |
主机 |
图像索引 |
nvtiffImageInfo_t *image_info |
输出 |
主机 |
指向 nvtiffImageInfo_t 的指针 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffStreamGetImageGeometry()¶
检索图像几何相关信息。几何信息包括图像是使用条带还是瓦片及其相应的尺寸。
签名:
nvtiffStatus_t nvtiffStreamGetImageGeometry(nvtiffStream_t tiff_stream,
uint32_t image_id,
nvtiffImageGeometry_t* geometry);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
tiff 流句柄 |
uint32_t image_id |
输入 |
主机 |
图像索引 |
nvtiffImageGeometry_t* geometry |
输入/输出 |
主机 |
指向 nvtiffImageGeometry_t 的指针 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffStreamGetGeoKeyInfo()¶
检索有关 GeoTIFF 密钥 中定义的地理密钥的信息。此信息对于检索与地理密钥关联的值非常有用。
签名:
nvtiffStatus_t nvtiffStreamGetGeoKeyInfo(nvtiffStream_t tiff_stream,
nvtiffGeoKey_t key,
uint32_t *size,
uint32_t *count,
nvtiffGeoKeyDataType_t* type)
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
tiff 流句柄 |
nvtiffGeoKey_t key |
输入 |
主机 |
GeoTIFF 密钥 |
uint32_t *size |
输出 |
主机 |
指向存储在密钥中的每个值的大小（以字节为单位）的指针 |
uint32_t *count |
输出 |
主机 |
指向存储在密钥中的值的数量的指针 |
nvtiffGeoKeyDataType_t *type |
输出 |
主机 |
指向存储在密钥中的值的数据类型的指针 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffStreamGetNumberOfGeoKeys()¶
检索 TIFF 文件中存在的地理密钥列表及其计数。此信息稍后可用于检索与每个地理密钥关联的值。
签名:
nvtiffStatus_t nvtiffStreamGetNumberOfGeoKeys(nvtiffStream_t tiff_stream,
nvtiffGeoKey_t* key,
uint32_t *num_keys)
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
tiff 流句柄 |
nvtiffGeoKey_t *key |
输出 |
主机 |
指向用户分配的缓冲区的指针，用于存储 TIFF 文件中的所有地理密钥（可以为 |
uint32_t *num_keys |
输出 |
主机 |
指向存储在 TIFF 文件中的地理密钥数量的指针 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffStreamGetTagInfo()¶
检索有关 TIFF 标签 中定义的 TIFF 标签的信息。此信息稍后可用于检索与 TIFF 标签关联的值。
签名:
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);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
tiff 流句柄 |
uint32_t image_id |
输入 |
主机 |
图像索引 |
nvtiffTag_t tiff_tag |
输入 |
主机 |
tiff 标签 |
nvtiffTagDataType_t *tag_type, |
输出 |
主机 |
指向缓冲区的指针，该缓冲区包含 |
uint32_t *size |
输出 |
主机 |
指向缓冲区的指针，该缓冲区包含 |
uint32_t *count |
输出 |
主机 |
指向缓冲区的指针，该缓冲区包含 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffStreamGetTagValue()¶
检索存储在 TIFF 标签中的值。
签名:
nvtiffStatus_t nvtiffStreamGetTagValue(nvtiffStream_t tiff_stream,
uint32_t image_id,
nvtiffTag_t tiff_tag,
void *tag_value,
uint32_t count);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
tiff 流句柄 |
uint32_t image_id |
输入 |
主机 |
图像索引 |
nvtiffTag_t tiff_tag |
输入 |
主机 |
tiff 标签 |
void *tag_value |
输出 |
主机 |
指向缓冲区的指针，该缓冲区包含与 |
uint32_t *count |
输出 |
主机 |
指向缓冲区的指针，该缓冲区包含 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffStreamGetGeoKey()¶
检索与存储在 TIFF 文件中的给定地理密钥关联的值。
签名:
nvtiffStatus_t nvtiffStreamGetGeoKey(nvtiffStream_t tiff_stream,
nvtiffGeoKey_t key,
void *val,
uint32_t count);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
tiff 流句柄 |
nvtiffGeoKey_t key |
输入 |
主机 |
要检索信息的地理密钥 |
void *val |
输出 |
主机 |
指向用户分配的缓冲区的指针，用于存储与 |
uint32_t count |
输入 |
主机 |
复制的值的数量（对于 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffStreamGetGeoKeyASCII()¶
检索与具有 ASCII 值的地理密钥关联的值。
签名:
nvtiffStatus_t NVTIFFAPI nvtiffStreamGetGeoKeyASCII(nvtiffStream_t tiff_stream,
nvtiffGeoKey_t key,
char* szStr,
uint32_t szStrMaxLen)
参数:
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
tiff 流句柄 |
nvtiffGeoKey_t key |
输入 |
主机 |
要检索信息的地理密钥 |
char *szStr |
输出 |
主机 |
指向用户分配的缓冲区的指针，该缓冲区包含密钥值 |
uint32_t szStrMaxLen |
输入 |
主机 |
用户分配的缓冲区 |
返回值:
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffStreamGetGeoKeySHORT()¶
检索与具有 SHORT 值的地理密钥关联的值。
签名:
nvtiffStatus_t NVTIFFAPI nvtiffStreamGetGeoKeySHORT(nvtiffStream_t tiff_stream,
nvtiffGeoKey_t key,
unsigned short *val,
uint32_t index,
uint32_t count)
参数:
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
tiff 流句柄 |
nvtiffGeoKey_t key |
输入 |
主机 |
要检索信息的地理密钥 |
unsigned short *val |
输出 |
主机 |
指向用户分配的缓冲区的指针，该缓冲区包含密钥值 |
uint32_t count |
输入 |
主机 |
需要复制到 |
uint32_t index |
输入 |
主机 |
要复制到 |
返回值:
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffStreamGetGeoKeyDOUBLE()¶
检索与具有 DOUBLE 值的地理密钥关联的值。
签名:
nvtiffStatus_t NVTIFFAPI nvtiffStreamGetGeoKeyDOUBLE(nvtiffStream_t tiff_stream,
nvtiffGeoKey_t key,
double *val,
uint32_t index,
uint32_t count)
参数:
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
tiff 流句柄 |
nvtiffGeoKey_t key |
输入 |
主机 |
要检索信息的地理密钥 |
double *val |
输出 |
主机 |
指向用户分配的缓冲区的指针，该缓冲区包含密钥值 |
uint32_t count |
输入 |
主机 |
需要复制到 |
uint32_t index |
输入 |
主机 |
要复制到 |
返回值:
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
解码 API 参考¶
nvtiffDecode()¶
解码 tiff_stream 中指定的 GPU 上的图像数据。TIFF 文件中的每个图像都会复制到“imageOut_d”指向的相应缓冲区中。此函数是完全异步的。
当图像的光度解释为 NVTIFF_PHOTOMETRIC_PALETTE 或 NVTIFF_PHOTOMETRIC_YCBCR 时，解码输出将被转换为 RGB。
对于具有多个采样的图像，解码输出将始终为平面连续格式。
签名
nvtiffStatus_t nvtiffDecode(nvtiffStream_t tiff_stream,
nvtiffDecoder_t nvtiff_decoder,
unsigned char **image_out,
cudaStream_t cuda_stream);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
|
nvtiffDecoder_t nvtiff_decoder |
输入 |
主机 |
解码器句柄 |
unsigned char **imageOut_d |
输出 |
主机 |
主机数组（大小为 TIFF 文件中的 num_images）指向设备缓冲区的指针数组。每个设备缓冲区应具有 image_width * image height * bitdepth * samples_per_pixel 的大小。当图像的光度解释为调色板模式时，设备缓冲区应具有 image_width * image height * 3 * 2 的大小 |
cudaStream_t cuda_stream |
输入 |
主机 |
|
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffDecodeRange()¶
此函数类似于 nvtiffDecode()。它允许用户指定要解码的图像范围（而不是解码文件中的所有图像）。
当图像的光度解释为 NVTIFF_PHOTOMETRIC_PALETTE 或 NVTIFF_PHOTOMETRIC_YCBCR 时，解码输出将被转换为 RGB。
对于具有多个采样的图像，解码输出将始终为平面连续格式。
签名
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);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
|
nvtiffDecoder_t nvtiff_decoder |
输入 |
主机 |
解码器句柄 |
unsigned int sub_file_start |
输入 |
主机 |
要解码的第一个图像的索引，在 [0, tiff_info.num_sub_files) 范围内。 |
unsigned int sub_file_num |
输入 |
主机 |
要解码的图像数量，从 |
unsigned char **imageOut_d |
输出 |
主机 |
主机数组（大小为 TIFF 文件中的 num_images）指向设备缓冲区的指针数组。每个设备缓冲区应具有 image_width * image height * bitdepth * samples_per_pixel 的大小。当图像的光度解释为调色板模式时，设备缓冲区应具有 image_width * image height * 3 * 2 的大小 |
cudaStream_t cuda_stream |
输入 |
主机 |
|
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffDecodeImage()¶
在 GPU 上解码在 tiff_stream 中指定的单个图像。该函数相对于主机是异步的。可以使用 nvtiffDecodeParams_t 实例来额外控制解码输出。
签名
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);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
|
nvtiffDecoder_t nvtiff_decoder |
输入 |
主机 |
解码器句柄 |
nvtiffDecodeParams_t params |
输入 |
主机 |
用于控制解码输出（例如指定 ROI、输出格式）。 |
uint32_t image_id |
输入 |
主机 |
对应于多图像 TIFF 文件中的图像索引（IFD）。不能超过 TIFF 文件中的图像总数。 |
void* image_out_d |
输出 |
设备 |
解码输出缓冲区。有关分配大小，请参阅 nvtiffDecodeParamsSetOutputFormat() |
cudaStream_t cuda_stream |
输入 |
主机 |
|
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffDecodeCheckSupported()¶
帮助确定 nvTIFF 是否可以解码由 tiff_stream 指定的 tiff 文件中的任何给定图像。如果图像受支持，则返回 NVTIFF_STATUS_SUCCESS
签名
nvtiffStatus_t nvtiffDecodeCheckSupported(nvtiffStream_t tiff_stream,
nvtiffDecoder_t decoder,
nvtiffDecodeParams_t params,
uint32_t image_id);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffStream_t tiff_stream |
输入 |
主机 |
|
nvtiffDecoder_t nvtiff_decoder |
输入 |
主机 |
解码器句柄 |
nvtiffDecodeParams_t params |
输入 |
主机 |
用于控制解码输出（例如指定 ROI、输出格式）。 |
uint32_t image_id |
输入 |
主机 |
对应于多图像 TIFF 文件中的图像索引（IFD）。不能超过 TIFF 文件中的图像总数。 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
解码参数 API 参考¶
此类别下的 API 用于初始化解码参数，作为 nvtiffDecodeParams_t 句柄的一部分。初始化后，该句柄可以作为输入传递给 nvtiffDecodeImage()
nvtiffDecodeParamsSetOutputFormat()¶
用于设置解码输出格式。有关详细信息，请参阅 解码输出格式。默认值为 NVTIFF_OUTPUT_UNCHANGED_I。
注意
当光度解释为 NVTIFF_PHOTOMETRIC_YCBCR 且压缩为 NVTIFF_COMPRESSION_JPEG 时，输出格式必须设置为 NVTIFF_OUTPUT_RGB_I_UINT8 或 NVTIFF_OUTPUT_RGB_I_UINT16。
注意
当光度解释为 NVTIFF_PHOTOMETRIC_MASK 时，只能使用 NVTIFF_OUTPUT_UNCHANGED_I。
当将输出格式设置为 NVTIFF_OUTPUT_UNCHANGED_I 时 -
当 bits_per_pixel 是 8 的倍数时，解码输出缓冲区的字节大小应为 image_width * image_height * (bits_per_pixel/8)
当 bits_per_pixel 小于 8 时，解码输出缓冲区的字节大小应为 (image_width * bits_per_pixel + 7)/8 * image_height
当将输出设置为 NVTIFF_OUTPUT_RGB_I_UINT8 时 -
解码输出缓冲区的字节大小应为 image_width * image_height * 3 * sizeof(uint8_t)
当将输出设置为 NVTIFF_OUTPUT_RGB_I_UINT16 时 -
解码输出缓冲区的字节大小应为 image_width * image_height * 3 * sizeof(uint16_t)
签名
nvtiffStatus_t nvtiffDecodeParamsSetOutputFormat(nvtiffDecodeParams_t decode_params,
nvtiffOutputFormat_t format);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffDecodeParams_t decode_params |
输入/输出 |
主机 |
解码输出参数句柄。 |
nvtiffOutputFormat_t format |
输入 |
主机 |
输出格式值。默认为 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
nvtiffDecodeParamsSetROI()¶
用于设置解码的感兴趣区域。默认情况下，解码整个图像。
offset_x 和 offset_y 应大于或等于 0，且分别不能超过图像宽度和高度。
offset_x + roi_width 和 offset_y + roi_height 分别不能超过图像宽度和图像高度。
当图像位深为 1 时，offset_x 和 roi_width 应为 8 的倍数
签名
nvjpeg2kStatus_t nvtiffDecodeParamsSetROI(nvtiffDecodeParams_t decode_params,
int32_t offset_x,
int32_t offset_y,
int32_t roi_width,
int32_t roi_height)
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvtiffDecodeParams_t decode_params |
输入/输出 |
主机 |
解码输出参数句柄 |
int32_t offset_x |
输入 |
主机 |
图像沿水平方向相对于左上角的偏移量。 |
int32_t offset_y |
输入 |
主机 |
图像沿垂直方向相对于左上角的偏移量。 |
int32_t roi_width |
输入 |
主机 |
相对于 offset_x 的图像宽度 |
int32_t roi_height |
输入 |
主机 |
相对于 offset_y 的图像高度 |
返回值
nvtiffStatus_t - 错误代码，如 解码 API 返回状态代码 中指定
编码 API 参考¶
nvTiffEncodeCtxCreate()¶
此函数基于指定的参数创建编码上下文，该上下文可用于执行图像的并行 LZW 压缩。
签名
nvTiffEncodeCtx_t nvTiffEncodeCtxCreate(int dev,
unsigned int imagesMax,
unsigned int stripsPerImageMax,
size_t memLimit=0);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
int dev |
输入 |
用于 CUDA 调用和内核启动的设备 |
|
unsigned int imagesMax |
输入 |
使用返回的上下文将编码的最大图像数 |
|
unsigned int stripsPerImageMax |
输入 |
使用返回的上下文将编码的图像将要分区的最大条带数 |
|
size_t memLimit |
输入 |
可用于分配条带压缩内核所需的内部缓冲区的最大设备内存量 |
返回值
SUCCESS - 成功时返回指向 nvTiffEncodeCtx_t 的指针
NULL - 否则。
nvTiffEncodeCtxDestroy()¶
销毁上下文 ctx，释放主机和设备上所有已分配的内存。
签名
void nvTiffEncodeCtxDestroy(nvTiffEncodeCtx_t *ctx);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvTiffEncodeCtx_t *ctx |
输入 |
销毁上下文 ctx，释放主机和设备上所有已分配的内存。 |
nvTiffEncode()¶
使用编码上下文指定的资源执行多个图像的编码。每个图像被分成由连续行组形成的条带，然后使用 LZW 独立压缩每个条带。
此函数是完全异步的。
签名
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);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvTiffEncodeCtx_t *ctx |
输入 |
由 nvTiffEncodeCtxCreate() 返回的 nvTiffEncodeCtx_t； |
|
unsigned int nrow |
输入 |
要压缩的图像的行数； |
|
unsigned int ncol |
输入 |
要压缩的图像的列数； |
|
unsigned int pixelSize |
输入 |
要压缩的图像的像素大小（以字节为单位）； |
|
unsigned int rowsPerStrip |
输入 |
要在单个条带中一起压缩的行数； |
|
unsigned int nImages |
输入 |
要压缩的图像数； |
|
unsigned char **images_d |
输入 |
主机 |
大小为 nImages 的主机数组，包含指向设备缓冲区的指针 |
unsigned long long stripAllocSize |
输入 |
压缩条带的估计最大大小； |
|
unsigned int *stripSize_d |
输出 |
设备 |
设备数组，大小至少为 ceil(nrow/rowsPerStrip)*nImages |
unsigned int *stripOffs_d |
输出 |
设备 |
设备数组，大小至少为 ceil(nrow/rowsPerStrip)*nImages |
unsigned long long *stripData_d |
输出 |
设备 |
设备数组，大小至少为 ceil(nrow/rowsPerStrip)*nImages*stripAllocSize，压缩后的条带将在此数组中返回 |
stream |
输入 |
用于内核启动的流 |
返回值
NVTIFF_ENCODE_SUCCESS - 成功时，可以在后续调用 nvTiffEncodeFinalize() 后访问压缩后的条带，请参阅下文；
NVTIFF_ENCODE_INVALID_CTX - ctx 无效。
NVTIFF_ENCODE_INVALID_STRIP_NUM - 如果指定的 nrow、rowsPerStrip 和 nImages 产生的要压缩的条带数大于在创建上下文 ctx 时由参数 imagesMax 和 stripsPerImageMax 指定的数量；
CUTIFF_ENCODE_INVALID_IMAGE_NUM: 如果指定的 nImages 大于在创建上下文 ctx 时由参数 imagesMax 指定的数量；
nvTiffEncodeFinalize()¶
此函数完成由 nvTiffEncode() 启动的压缩过程。由于 nvTiffEncode() 是异步的，因此通过此终结调用检查有关其运行时操作的状态。请注意，此函数不是完全异步的。在入口处，它在指定为参数的流上同步，并且如果先前 cuTiffEncode() 调用启动的所有操作都成功终止，则它会异步启动一个内核，以最终确定传递给 cuTiffEncode() 的数据数组（stripSize_d、stripOffs_d 和 stripData_d）。因此，在访问这些数组之前，必须在传递的流上同步。
签名
int nvTiffEncodeFinalize(nvTiffEncodeCtx_t *ctx,
cudaStream_t stream=0);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
nvTiffEncodeCtx_t *ctx |
输入 |
传递给 nvTiffEncode() 的 nvTiffEncodeCtx_t； |
|
stream |
输入 |
用于内核启动的流 |
返回值
NVTIFF_ENCODE_SUCCESS - 成功时；在流上排队的所有操作完成后，可以在传递给 nvTiffEncode() 的数组 stripSize_d、stripOffs_d、stripData_d 中访问条带大小、偏移量和数据；
NVTIFF_ENCODE_INVALID_CTX - ctx 无效。
NVTIFF_ENCODE_COMP_STRIP_TOO_LONG - 当前压缩过程支持压缩大小最大为 48KB 的条带；如果一个条带将被压缩成更大的尺寸，则返回此错误
NVTIFF_ENCODE_COMP_OVERFLOW - 如果一个或多个条带压缩到大于传递给 nvTiffEncode() 的参数 stripAllocSize 值的大小，则返回此错误
nvTiffWriteFile()¶
这是一个方便的函数，用于将压缩图像写入单个 TIFF 文件。库用户可能希望实现自己的函数以使用其他/自定义 TIFF 标签。
签名
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);
参数
参数 |
输入/输出 |
内存 |
描述 |
|---|---|---|---|
const char *fname |
输入 |
主机 |
输出 TIFF 文件的名称； |
int tiffVer |
输入 |
指定是使用常规 Tiff 还是 BigTiff 文件格式；对于常规 Tiff，请使用 VER_REG_TIFF；对于 BigTiff，请使用 VER_BIG_TIFF； |
|
unsigned int nImages |
输入 |
要写入文件的图像数量 |
|
unsigned int nrow |
输入 |
每个图像的行数 |
|
unsigned int ncol |
输入 |
每个图像的列数； |
|
unsigned int rowsPerStrip |
输入 |
构成 Tiff 条带的行数 |
|
unsigned short samplesPerPixel |
输入 |
每个像素的组件数 |
|
unsigned short bitsPerSample |
输入 |
长度为 samplesPerPixel 的数组，指定每个组件的位数； |
|
unsigned int photometricInt |
输入 |
图像数据的颜色空间；支持的值：1 或 2； |
|
unsigned int planarConf |
输入 |
每个像素的组件如何存储；支持的值：1（chunky 格式）； |
|
unsigned long long *stripSize |
输入 |
主机 |
大小为 ceil(nrow/rowsPerStrip)*nImages 的主机数组，包含压缩条带的长度； |
unsigned long long *stripOffs |
输入 |
主机 |
大小为 ceil(nrow/rowsPerStrip)*nImages 的主机数组，包含压缩条带在 stripData 缓冲区内的起始偏移量； |
unsigned char *stripData |
输入 |
主机 |
主机数组，包含 ceil(nrow/rowsPerStrip)*nImages 个压缩条带；条带应按顺序存储，从第一个图像到最后一个图像，从上到下； |
返回值
NVTIFF_WRITE_SUCCESS - 成功时
NVTIFF_WRITE_UNSUPP_PLANAR_CONF - 如果 planarConf 参数的值不等于 1；。
NVTIFF_WRITE_UNSUPP_PHOTOMETRIC_INT - 如果 photometricInt 参数的值既不是 1 也不是 2；