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,

  1. Determine the size of the buffer you’ll need to hold the raw data using ScanImageTiffReader_GetDataSizeBytes().
  2. Allocate the memory you need.
  3. 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:

  1. Determine the size of the buffer you need using ScanImageTiffReader_GetMetadataSizeBytes().
  2. 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:

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.

Return
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.

Return
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.

Return
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.

Return
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.

Return
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.

Return
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.

Return
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

Return
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

Return
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

Return
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

Return
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.

Return
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.

Return
0 on failure, otherwise the number of indexible frames.
See
ScanImageTiffReader_GetImageDescriptionCount

EXPORT size_t ScanImageTiffReader_GetFrameIntervalSizeBytes(ScanImageTiffReader * r, unsigned beg, unsigned end)

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

Return
0 on failure, otherwise the number of bytes required to store the raw image data in the interval of frames from “beg” up to, but not including, “end”.

EXPORT int ScanImageTiffReader_GetFrameInterval(ScanImageTiffReader * r, unsigned beg, unsigned end, char * buf, size_t bytesof_buf)

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

Fills “buf” with raw image data from the interval of frames starting at “beg” and up to, but not including, “end”.

Return
0 on failure, otherwise 1

struct ScanImageTiffReader

Public Members

void *handle

A pointer to the (abstract) file context

const char *log

If not NULL, there was an error and this points to a NULL-terminate char string with additional information.