C Library¶

The C API is provided as a static or shared library. It requires no dependencies. We try to statically link wherever possible.

Open/Close¶

Use ScanImageTiffReader_Open() to open a file. When you’re done call ScanImageTiffReader_Close() to close any open file handles and cleanup any other resources in use.

Error handling¶

When errors occur, functions usually return a 0. Any error messages will be contained in the log field of the ScanImageTiffReader context object. Normally the log string is NULL; only after an error does it point to a null-terminated string.

Image data¶

To read the image data,

Determine the size of the buffer you’ll need to hold the raw data using ScanImageTiffReader_GetDataSizeBytes().

Allocate the memory you need.

Read using ScanImageTiffReader_GetData(). This loads the entire volume into memory. There’s no option for reading just a subset of the data.

One nice thing about ScanImageTiffReader_GetData() is that many asynchronous read requests are made at once. This typically means that read commands will be coallesced and queued by the operating system so that very high read bandwidths can be acheived.

Metadata¶

Reading metadata follows a similar pattern. To read the frame-invariant metadata:

Determine the size of the buffer you need using ScanImageTiffReader_GetMetadataSizeBytes().

Read it using ScanImageTiffReader_GetMetadata().

The frame-varying metadata is read using a similar pattern. There are two sets of functions for reading the frame varying data:

ScanImageTiffReader_GetImageDescription() reads the image description for a single frame.

ScanImageTiffReader_GetAllImageDescriptions() reads the image descriptions for all frames into a single buffer.

C API¶

Typedefs

typedef struct ScanImageTiffReader ScanImageTiffReader¶

Functions

EXPORT ScanImageTiffReader ScanImageTiffReader_Open (const char *filename)

On failure, the log field in the returned object will be non-null. It will point to an error string.

Returns: a ScanImageTiffReader object

EXPORT void ScanImageTiffReader_Close (ScanImageTiffReader *r)

EXPORT int ScanImageTiffReader_GetImageDescriptionCount (ScanImageTiffReader *r)

On failure, the log field in the returned object will be non-null. It will point to an error string.

Returns: 0 on failure, otherwise the number of indexible frames for querying image descriptions.

EXPORT size_t ScanImageTiffReader_GetImageDescriptionSizeBytes (ScanImageTiffReader *r, int iframe)

On failure, the log field in the returned object will be non-null. It will point to an error string.

Returns: 0 on failure, otherwise the number of bytes required to store the image description string of frame i.

EXPORT int ScanImageTiffReader_GetImageDescription (ScanImageTiffReader *r, int iframe, char *buf, size_t bytes_of_buf)

On failure, the log field in the returned object will be non-null. It will point to an error string.

Returns: on success, otherwise 0

EXPORT size_t ScanImageTiffReader_GetAllImageDescriptionsSizeBytes (ScanImageTiffReader *r)

On failure, the log field in the returned object will be non-null. It will point to an error string.

Returns: 0 on failure, otherwise the number of bytes required to store the concatenated image descriptions from all frames.

EXPORT int ScanImageTiffReader_GetAllImageDescriptions (ScanImageTiffReader *r, char *buf, size_t bytes_of_buf)

On failure, the log field in the returned object will be non-null. It will point to an error string.

Returns: 1 on success, otherwise 0

EXPORT size_t ScanImageTiffReader_GetMetadataSizeBytes (ScanImageTiffReader *r)

On failure, the log field in the returned object will be non-null. It will point to an error string.

Returns: 0 on failure, otherwise the size of the metadata section in bytes.

EXPORT int ScanImageTiffReader_GetMetadata (ScanImageTiffReader *r, char *buf, size_t bytes_of_buf)

On failure, the log field in the returned object will be non-null. It will point to an error string

Returns: 0 on failure, otherwise 1

EXPORT size_t ScanImageTiffReader_GetDataSizeBytes (ScanImageTiffReader *r)

On failure, the log field in the returned object will be non-null. It will point to an error string

Returns: 0 on failure, otherwise the size of the metadata section in bytes.

EXPORT int ScanImageTiffReader_GetData (ScanImageTiffReader *r, char *buf, size_t bytes_of_buf)

On failure, the log field in the returned object will be non-null. It will point to an error string

Returns: 0 on failure, otherwise 1

EXPORT struct nd ScanImageTiffReader_GetShape (ScanImageTiffReader *r)

On failure, the log field in the returned object will be non-null. It will point to an error string

Returns: 0 on failure, otherwise a zero’d out struct nd object.

EXPORT const char * ScanImageTiffReader_APIVersion ()

Identifyies the version of this API. Use this for support and for adapting your code if the API changes significantly in the future.

Returns: a null-terminated string

EXPORT unsigned ScanImageTiffReader_GetFrameCount (ScanImageTiffReader *r)

On failure, the log field in the returned object will be non-null. It will point to an error string.

The “frame count” and the “image description count” are identical.