SIF: sif-io.h File Reference

#include "SIFExport.h"
#include <sys/types.h>
#include <stdio.h>


Data Structures
struct	sif_header
	A struct for storing a SIF file header in memory. More...
struct	sif_tile
	A struct for storing a SIF tile header in memory. It stores important information related to a tile, including which of its bands are uniform, and the uniform pixel values of the bands. More...
struct	sif_meta_data
	A struct for storing meta-data in memory. It stores a node in a linked list of meta-data. More...
struct	sif_file
	A struct for storing necessary data for the processing of an open file. More...
Defines
#define	LONGLONG long long
#define	SIF_ERROR_NONE 0
	A status code indicating no error has been detected for the processing of the target file.
#define	SIF_ERROR_MEM 1
	A status code indicating an error occurred while allocating or freeing memory.
#define	SIF_ERROR_NULL_FP 2
	A status code indicating a file could not be processed because the file pointer is null. Admittedly, there is no way to store this in the sif_file struct passed since it is null. However, setting a static variable for the caller to check is under consideration for a future version.
#define	SIF_ERROR_NULL_HDR 3
	A status code indicating a file could not be processed because the header pointer is null.
#define	SIF_ERROR_INVALID_BN 4
	A status code indicating a block number passed to a sif-io function was invalid (i.e. negative or out-of-bounds).
#define	SIF_ERROR_INVALID_TN 5
	A status code indicating a tile number passed to a sif-io function was invalid (i.e. negative or out-of-bounds).
#define	SIF_ERROR_READ 6
	A status code indicating an error occurred when reading from the file.
#define	SIF_ERROR_WRITE 7
	A status code indicating an error occurred when writing to the file.
#define	SIF_ERROR_SEEK 8
	A status code indicating an error occurred when seeking in the file.
#define	SIF_ERROR_TRUNCATE 9
	A status code indicating an error occurred when truncating the file.
#define	SIF_ERROR_INVALID_FILE_MODE 10
	A status code indicating that the file mode chosen is invalid. This usually occurs when a file is opened for update that is read-only or a opened when the permissions do not permit reading.
#define	SIF_ERROR_INCOMPATIBLE_VERSION 11
	A status code indicating that the currently loaded sif-io library is not capable of processing the version of a file. This is usually due to the fact that the file was written with a later version of the SIF format than the loaded library.
#define	SIF_ERROR_META_DATA_KEY 12
	Returned when a call is made that expects a key to be present when the key cannot be found.
#define	SIF_ERROR_META_DATA_VALUE 13
	Returned by `sif_get_meta_data` when the meta-data does not contain a null-terminated string.
#define	SIF_ERROR_CANNOT_WRITE_VERSION 14
	Returned by `sif_use_file_version` when the library is not capable of writing the file in the requested version.
#define	SIF_ERROR_INVALID_BAND 15
	Returned if a band argument passed is invalid.
#define	SIF_ERROR_INVALID_COORD 16
	Returned if a coordinate argument (e.g. `x` or `y`) is invalid.
#define	SIF_ERROR_INVALID_TILE_SIZE 17
	Returned if a tile size argument (e.g. `tile_width` or `tile_height`) is invalid.
#define	SIF_ERROR_INVALID_REGION_SIZE 18
	Returned if a region size argument (e.g. `width` or `height`) is invalid.
#define	SIF_ERROR_INVALID_BUFFER 19
	Returned if a tile size argument (e.g. `width` or `height`) is invalid.
#define	SIF_AGREEMENT_SIMPLE "simple"
	A value to set the data-type convention agreement (i.e. "_sif_agree") meta-data field to indicate that the `simple` data-type convention is used.
#define	SIF_AGREEMENT_GDAL "gdal"
	A value to set the data-type convention agreement (i.e. "_sif_agree") meta-data field to indicate that the `gdal` data-type convention is used.
#define	SIF_MAGIC_NUMBER "!SIF"
	A string representing the magic number. The obscure string used to easily identify a file as a file in SIF format.
#define	SIF_MAGIC_NUMBER_SIZE 8
	The number of bytes needed to store the magic number. The obscure string is used to easily identify that a file is likely to be in SIF format.
#define	SIF_SIMPLE_ERROR_UNDEFINED_DT 100
	An error indicating that the data type is not recognized as a data type in the simple data-type convention.
#define	SIF_SIMPLE_ERROR_INCORRECT_DT 101
	An error to indicate the data type of the image does not correspond to the data type requested.
#define	SIF_SIMPLE_ERROR_UNDEFINED_ENDIAN 102
	An error to indicate an endian code is invalid.
#define	SIF_SIMPLE_UINT8 0
	The base type code (i.e. `user_data_type mod 10`) for storing unsigned 8-bit integers.
#define	SIF_SIMPLE_INT8 1
	The base type code (i.e. `user_data_type mod 10`) for storing signed 8-bit integers.
#define	SIF_SIMPLE_UINT16 2
	The base type code (i.e. `user_data_type mod 10`) for storing unsigned 16-bit integers.
#define	SIF_SIMPLE_INT16 3
	The base type code (i.e. `user_data_type mod 10`) for storing signed 16-bit integers.
#define	SIF_SIMPLE_UINT32 4
	The base type code (i.e. `user_data_type mod 10`) for storing unsigned 32-bit integers.
#define	SIF_SIMPLE_INT32 5
	The base type code (i.e. `user_data_type mod 10`) for storing signed 32-bit integers.
#define	SIF_SIMPLE_UINT64 6
	The base type code (i.e. `user_data_type mod 10`) for storing unsigned 64-bit integers.
#define	SIF_SIMPLE_INT64 7
	The base type code (i.e. `user_data_type mod 10`) for storing signed 64-bit integers.
#define	SIF_SIMPLE_FLOAT32 8
	The base type code (i.e. `user_data_type mod 10`) for storing IEEE-754 standard 32-bit floats.
#define	SIF_SIMPLE_FLOAT64 9
	The base type code (i.e. `user_data_type mod 10`) for storing IEEE-754 standard 64-bit floats.
#define	SIF_SIMPLE_LITTLE_ENDIAN 0
	The endian code for little endian.
#define	SIF_SIMPLE_BIG_ENDIAN 1
	The endian code for little endian.
#define	SIF_SIMPLE_NATIVE_ENDIAN SIF_SIMPLE_LITTLE_ENDIAN
	The endian code for the byte order of the native machine on which this library runs.
#define	SIF_SIMPLE_ENDIAN(t) (((int)t)/10)
	A function macro that returns the endian code for a simple type code t.
#define	SIF_SIMPLE_TYPE_CODE(bt, ec) ((bt)+(ec))
	A function macro that computes the compound type code from the base type code bt and endian code ec.
#define	SIF_SIMPLE_BASE_TYPE_CODE(x) (((int)x)%10)
	A function macro that computes the base type code from the compound type code.
Functions
long	sif_get_version ()
	Return the latest version of the SIF file format that the currently loaded SIF library can process.
sif_file *	sif_open (const char *filename, int read_only)
	Open a Sparse Image File (SIF) format file for reading or update.
sif_file *	sif_create (const char *filename, long width, long height, long bands, int data_unit_size, int user_data_type, int consolidate_on_close, int defragment_on_close, long tile_width, long tile_height, int intrinsic_write)
	Create a new Sparse Image Format (SIF) file with a given filename and attributes. The file's header and tile headers are written. No space is preallocated for data blocks.
sif_file *	sif_create_copy (sif_file file, const char filename)
	Create a copy of a SIF file.
int	sif_close (sif_file *file)
	Close a SIF file.
void	sif_consolidate (sif_file *file)
	Check all tiles in a file for intrinsic uniformity.
void	sif_defragment (sif_file *file)
	Defragment the file.
void	sif_set_raster (sif_file file, const void data, long x, long y, long w, long h, long band)
	Writes a rectangular image region to a file.
void	sif_get_raster (sif_file file, void data, long x, long y, long w, long h, long band)
	Reads a rectangular raster region from a file. It may overlap multiple tiles in the file.
void	sif_fill_tiles (sif_file file, long band, const void value)
	Fill all tiles of a particular band with a constant value.
void	sif_get_tile_slice (sif_file file, void buffer, long tx, long ty, long band)
	Retrieve a tile slice.
void	sif_set_tile_slice (sif_file file, const void buffer, long tx, long ty, long band)
	Store a tile slice.
void	sif_fill_tile_slice (sif_file file, long tx, long ty, long band, const void value)
	Fill a tile slice with a constant value.
void	sif_set_meta_data (sif_file file, const char key, const char *value)
	Set a meta-data field with a given key to a value defined by a null-terminated character string.
void	sif_set_meta_data_binary (sif_file file, const char key, const void *buffer, int n_bytes)
	Set a meta-data field with a given key to a given sequence of bytes.
const char *	sif_get_meta_data (sif_file file, const char key)
	Get a string meta-data field with a given key. This function returns 0 and sets the error field in the file's header if the buffer stored for this meta-data is not a null-terminated string or if the field with the given key string could not be found.
const void *	sif_get_meta_data_binary (sif_file file, const char key, int *n_bytes)
	Get a string meta-data field with a given key. This function returns 0 and sets the error field in the file's header.
int	sif_is_shallow_uniform (sif_file file, long x, long y, long w, long h, long band, void uniform_value)
	Determine if the tiles comprising a region are shallow uniform.
int	sif_is_slice_shallow_uniform (sif_file file, long tx, long ty, long band, void uniform_value)
	Determine if a tile has shallow uniformity.
int	sif_flush (sif_file *file)
	Flush all remaining unwritten data to the file.
void	sif_set_user_data_type (sif_file *file, long user_data_type)
	Set the user data type for the file.
long	sif_get_user_data_type (sif_file *file)
	Get the user data type integer for the file.
void	sif_set_intrinsic_write (sif_file *file)
	Set the uniformity flag. This results in a pixel uniformity check on all dirty tiles.
int	sif_is_intrinsic_write_set (sif_file *file)
	Return the value of the uniformity flag. When true, a uniformity check is perfomed on all dirty tiles during close.
void	sif_unset_intrinsic_write (sif_file *file)
	Unset the uniformity flag.
void	sif_set_defragment (sif_file *file)
	Set the defragmentation flag.
int	sif_is_defragment_set (sif_file *file)
	Unsets the defragmentation flag.
void	sif_unset_defragment (sif_file *file)
	Set the defragmentation flag.
void	sif_set_consolidate (sif_file *file)
	Set the consolidation flag.
int	sif_is_consolidate_set (sif_file *file)
	Return whether the file will be scheduled for consolidation on its close. Used blocks are moved toward the begining of the file, taking up the space of unused blocks before them. If there are no unused blocks or all of the unused blocks are at the end of the file, this file is simply truncated at the location of the first byte of the unused block and the meta-data is rewritten.
void	sif_unset_consolidate (sif_file *file)
	Unset the consolidation flag.
void	sif_set_affine_geo_transform (sif_file file, const double trans)
	Set the affine georeferencing transform of an open file.
const double *	sif_get_affine_geo_transform (sif_file *file)
	Get the affine georeferencing transform of an open file.
const char *	sif_get_projection (sif_file *file)
	Return the projection string of an open file. It is expected to be in OpenGIS WKT format. The string is stored in the "_sif_proj" field in the meta-data region of the file. If the projection string cannot be found, the empty string is returned.
void	sif_set_projection (sif_file file, const char proj)
	Set the projection string of an open file. This is expected to be empty ("") or in OpenGIS WKT format. The string is stored in the "_sif_proj" field in the meta-data region of the file.
const char *	sif_get_agreement (sif_file *file)
	Return a string indicating the data type convention used in this file. If the string is `"gdal"` then the GDT type codes in the GDAL library are used. If the string is `"simple"` then the convention presented earlier in this document is used.
void	sif_set_agreement (sif_file file, const char agree)
	Set a string indicating the data type convention used in this file. If the string is "gdal" then the GDT type codes in the GDAL library are used. If the string is "simple" then the convention presented earlier in this document is used.
int	sif_get_meta_data_num_items (sif_file *file)
	Get the number of meta data (key, value) pairs in this file.
void	sif_get_meta_data_keys (sif_file file, const char *key_strs, int num_keys)
	Retrieve the keys of the meta data stored in the file. It is the responsibility of the caller to free the memory to which key_strs points but not (key_strs)[i] for any i, non-negative i < sif_header::n_keys.
void	sif_remove_meta_data_item (sif_file file, const char key)
	Removes a meta-data item by its key string.
void	sif_use_file_format_version (sif_file *file, long version)
	Specifies that when the file is written, the file should be written with using the SIF file format version specified. If the version is not supported for write, a SIF_ERROR_CANNOT_WRITE_VERSION error is set in the header's error code field.
int	sif_is_possibly_sif_file (const char *filename)
	Returns a positive value if the file referred to by `filename` could possibly be a SIF file.
const char *	sif_get_error_description (int code)
	Returns a description of a SIF error code.
sif_file *	sif_simple_create (const char *filename, long width, long height, long bands, int simple_data_type, int consolidate_on_close, int defragment_on_close, long tile_width, long tile_height, int intrinsic_write)
	Create a new Sparse Image Format (SIF) file with a given filename and attributes. The file's header and tile headers are written. No space is preallocated for data blocks. The simple data-type convention is used. When reading, writing, or filling the image file created by this function, the `sif_simple_*` functions must be used to ensure the image data elements are written with the proper byte order.
sif_file *	sif_simple_create_defaults (const char *filename, long width, long height, long bands, int simple_data_type)
	Create a new Sparse Image Format (SIF) file with a given filename and attributes. The file's header and tile headers are written. No space is preallocated for data blocks. The simple data-type convention is used.
void	sif_simple_set_endian (sif_file *file, int endian)
	Set the network byte order for the pixel. Note that this field should never be set once a raster is written to a file. This field must be set to one of SIF_SIMPLE_LITTLE_ENDIAN or SIF_SIMPLE_BIG_ENDIAN.
int	sif_simple_get_endian (sif_file *file)
	Get the network byte order of the pixel values in the image of this file.
void	sif_simple_set_data_type (sif_file *file, int code)
	Set the simple data type code for the pixel. Note that this field should never be set once a raster is written to a file.
int	sif_simple_get_data_type (sif_file *file)
	Get the simple data type code of the pixel values in the image of this file.
void	sif_simple_set_raster (sif_file file, const void data, long x, long y, long w, long h, long band)
	Write a rectangular region to a file. The byte order of the data values is automatically converted from host order to the the byte order of the file.
void	sif_simple_get_raster (sif_file file, void data, long x, long y, long w, long h, long band)
	Read a rectangular region from a file. The byte order of the data values in the buffer is automatically converted to the byte order of the file.
void	sif_simple_fill_tiles (sif_file file, long band, const void value)
	Fill a band with a constant value. The byte order of the value is converted to the byte order of the file's image.
void	sif_simple_get_tile_slice (sif_file file, void buffer, long tx, long ty, long band)
	Retrieve a tile slice. The byte order of the data values in the buffer are in host byte order.
void	sif_simple_set_tile_slice (sif_file file, const void buffer, long tx, long ty, long band)
	Store a tile slice. The byte order of the data values in the buffer are converted to the byte order of the file.
void	sif_simple_fill_tile_slice (sif_file file, long tx, long ty, long band, const void value)
	Fill a tile slice with a constant value. The value is converted from host order to the byte order in the file.
sif_file *	sif_simple_open (const char *filename, int read_only)
	Open a Sparse Image File (SIF) format file for reading or update. The file is expected to use the Simple data type convention.
int	sif_simple_is_shallow_uniform (sif_file file, long x, long y, long w, long h, long band, void uniform_value)
	Determine if the tiles comprising a region are shallow uniform. The "simple" data-type convention is assumed.
int	sif_simple_is_slice_shallow_uniform (sif_file file, long tx, long ty, long band, void uniform_value)
	Determine if a tile slice has shallow uniformity. The simple user data type convention is assumed.
int	sif_is_simple (sif_file *file)
int	sif_is_sif_simple (const char *filename)

Detailed Description

Define Documentation

#define LONGLONG long long

#define SIF_AGREEMENT_GDAL "gdal"

A value to set the data-type convention agreement (i.e. "_sif_agree") meta-data field to indicate that the gdal data-type convention is used.

#define SIF_AGREEMENT_SIMPLE "simple"

A value to set the data-type convention agreement (i.e. "_sif_agree") meta-data field to indicate that the simple data-type convention is used.

#define SIF_MAGIC_NUMBER "!**SIF**"

A string representing the magic number. The obscure string used to easily identify a file as a file in SIF format.

#define SIF_MAGIC_NUMBER_SIZE 8

The number of bytes needed to store the magic number. The obscure string is used to easily identify that a file is likely to be in SIF format.

#define SIF_SIMPLE_ERROR_INCORRECT_DT 101

An error to indicate the data type of the image does not correspond to the data type requested.

#define SIF_SIMPLE_ERROR_UNDEFINED_DT 100

An error indicating that the data type is not recognized as a data type in the simple data-type convention.

#define SIF_SIMPLE_ERROR_UNDEFINED_ENDIAN 102

An error to indicate an endian code is invalid.

Function Documentation

int sif_close ( sif_file * file )

Close a SIF file.

If the file is open for reading and writing, defragmentation and consolidation occur only if the defragment and consolidate flags are set in the file's header. The file header, tile headers, and meta data are written upon close.

Parameters:

file

The SIF file to close.

Returns:: The status of the close.

See also:

sif_header::consolidate

sif_header::defragment

sif_set_consolidate

sif_unset_consolidate

sif_is_consolidate_set

void sif_consolidate ( sif_file * file )

Check all tiles in a file for intrinsic uniformity.

If a tile is found to be intrinsically uniform, its common pixel values for each slice is stored in its header and the physical storage block it is using is freed. If the consolidation flag in the file's header is turned off or the file is read only, this method does nothing.

Parameters:

file

The file to mark for uniformity.

sif_file* sif_create	(	const char *	filename,
		long	width,
		long	height,
		long	bands,
		int	data_unit_size,
		int	user_data_type,
		int	consolidate_on_close,
		int	defragment_on_close,
		long	tile_width,
		long	tile_height,
		int	intrinsic_write
	)

Create a new Sparse Image Format (SIF) file with a given filename and attributes. The file's header and tile headers are written. No space is preallocated for data blocks.

Parameters:

	filename	The filename of the new file.
	width	The width of the image to store in the file to create.
	height	The height of the image to store in the file to create.
	bands	The number of bands of the image to store in the file to create.
	data_unit_size	The size of a single pixel in bytes, e.g. `sizeof(pixel_data_type)`.
	user_data_type	A user-defined data type. The SIF I/O functions do not look at this value. This is strictly for the user's reference when opening a pre-existing file.
	consolidate_on_close	Defines whether an intrinsic uniformity check should be applied to dirty tiles during each close.
	defragment_on_close	Defines whether the file should be defragmented during each close.
	tile_width	The width of a single tile.
	tile_height	The height of a single tile.
	intrinsic_write	Defines whether intrinsic uniformity checks should be performed when rasters are written to a file.

Returns:: A file structure containing the constructs needed to manipulate the file created by this function. This function returns NULL if an error occurs during creation.

sif_file* sif_create_copy	(	sif_file *	file,
		const char *	filename
	)

Create a copy of a SIF file.

Warning:: Note that this function has neither been tested nor ported for use with WIN32+MSVS.

Parameters:

	file	The file structure pointing to the file to copy. This file is flushed before its contents are read.
	filename	The filename of the file to store the copy.

Returns:: A file structure containing the constructs needed to manipulate the file copied by this function. This function returns NULL if an error occurs during file creation.

void sif_defragment ( sif_file * file )

Defragment the file.

This results in a sort of the storage blocks so they are in the order of their corresponding tile indices. This enables faster reading/writing of continguous blocks. No unused storage blocks remain in the file (i.e. the used blocks are shifted so that they write over the unused blocks). The file is truncated at the position of the last used storage block byte. Meta-data and the file's header are rewritten.

Parameters:

file

The file to defragment.

void sif_fill_tile_slice	(	sif_file *	file,
		long	tx,
		long	ty,
		long	band,
		const void *	value
	)

Fill a tile slice with a constant value.

If all bands become uniform as a result of this fill, the block for this slice's corresponding cube will be freed.

Warning:: This function has not been tested.

Parameters:

	file	The file on which to perform the fill.
	tx	The horizontal index of the tile to fill (0..N-1 indexed).
	ty	The vertical index of the tile to fill (0..N-1 indexed).
	band	The band index of the tile to fill (0..N-1 indexed).
	value	The value to fill all values of the slice. It must be sif_header::data_unit_size bytes in size.

See also:: sif_fill_tiles

void sif_fill_tiles	(	sif_file *	file,
		long	band,
		const void *	value
	)

Fill all tiles of a particular band with a constant value.

If uniformity results as a result of this fill, the corresponding tiles are marked appropriately and the block space they use is freed.

Parameters:

	file	The file on which to perform the fill.
	band	The band index of the tile to retrieve (0..N-1 indexed).
	value	The value to fill all values of the slice. It must be data_unit_size in bytes.

int sif_flush ( sif_file * file )

Flush all remaining unwritten data to the file.

This function immediately returns if the file passed is read-only.

Parameters:

file

The SIF file to flush.

Returns:: A non-zero value if no error occurred during the flush.

const double* sif_get_affine_geo_transform ( sif_file * file )

Get the affine georeferencing transform of an open file.

Parameters:

file

The file to get the transform.

Returns:: An array of six doubles representing the transform.

See also:: sif_set_affine_geo_transform
sif_header::affine_geo_transform

const char* sif_get_agreement ( sif_file * file )

Return a string indicating the data type convention used in this file. If the string is "gdal" then the GDT type codes in the GDAL library are used. If the string is "simple" then the convention presented earlier in this document is used.

Parameters:

file

The file from which to get the projection string.

Returns:: The convention agreement string.

See also:: sif_set_agreement

const char* sif_get_error_description ( int code )

Returns a description of a SIF error code.

Parameters:

code

The code of the error.

Returns:: A description of the error as a string.

const char* sif_get_meta_data	(	sif_file *	file,
		const char *	key
	)

Get a string meta-data field with a given key. This function returns 0 and sets the error field in the file's header if the buffer stored for this meta-data is not a null-terminated string or if the field with the given key string could not be found.

Parameters:

	file	The file on which to set the meta-data field.
	key	The key of the field to set.

Returns:: The value of the field.

See also:

sif_get_meta_data_binary

sif_set_meta_data

sif_set_meta_data_binary

const void* sif_get_meta_data_binary	(	sif_file *	file,
		const char *	key,
		int *	n_bytes
	)

Get a string meta-data field with a given key. This function returns 0 and sets the error field in the file's header.

Parameters:

	file	The file to set the meta-data.
	key	The key of the field to set.
	n_bytes	A pointer to an integer value. This value is set to the size of the buffer returned.

Returns:: The value of the field.

void sif_get_meta_data_keys	(	sif_file *	file,
		const char ***	key_strs,
		int *	num_keys
	)

Retrieve the keys of the meta data stored in the file. It is the responsibility of the caller to free the memory to which *key_strs points but not (*key_strs)[i] for any i, non-negative i < sif_header::n_keys.

Parameters:

	file	The file from which to retrieve the meta-data keys.
	key_strs	A pointer pointing to the pointer to set to the location of the array of strings. The last value of the array of strings is set to 0 (sentinel).
	num_keys	A pointer to the int to store the number of keys retrieved by this function.

int sif_get_meta_data_num_items ( sif_file * file )

Get the number of meta data (key, value) pairs in this file.

Parameters:

file

The file from which to get the number of meta-data items.

const char* sif_get_projection ( sif_file * file )

Return the projection string of an open file. It is expected to be in OpenGIS WKT format. The string is stored in the "_sif_proj" field in the meta-data region of the file. If the projection string cannot be found, the empty string is returned.

Parameters:

file

The file from which to get the projection string.

Returns:: The projection string.

See also:: sif_set_projection

void sif_get_raster	(	sif_file *	file,
		void *	data,
		long	x,
		long	y,
		long	w,
		long	h,
		long	band
	)

Reads a rectangular raster region from a file. It may overlap multiple tiles in the file.

Warning:: This function has not been tested.

Parameters:

	file	The file on which to read the raster plane out.
	data	The buffer to store the raster plane.
	x	The starting horizontal pixel offset (0..N-1 indexed) to read.
	y	The starting vertical pixel offset (0..N-1 indexed) to read.
	w	The width of the region.
	h	The height of the region.
	band	The band offset (0..N-1 indexed).

See also:

sif_set_raster

sif_get_tile_slice

sif_set_tile_slice

void sif_get_tile_slice	(	sif_file *	file,
		void *	buffer,
		long	tx,
		long	ty,
		long	band
	)

Retrieve a tile slice.

If the tile is uniform, no access to the disk is made; instead, the uniform pixel value for the band in the tile's header is used to fill the buffer. The buffer must contain enough bytes to hold a slice.

Parameters:

	file	The file on which to perform the fill.
	tx	The horizontal index of the slice to retrieve (0..N-1 indexed).
	ty	The vertical index of the slice to retrieve (0..N-1 indexed).
	band	The band index of the slice to retrieve (0..N-1 indexed).
	buffer	The buffer to store the tile slice. It must be data_unit_size in bytes.

See also:: sif_fill_tile_slice

long sif_get_user_data_type ( sif_file * file )

Get the user data type integer for the file.

This value does not change the behavior of any sif-io.h functions. The user may use it to store an integer representing the data type of the pixel values in the image.

Parameters:

file

The file on which to get the user-defined data type flag.

Returns:: The user-defined data type of the data units in the file.

long sif_get_version ( )

Return the latest version of the SIF file format that the currently loaded SIF library can process.

Returns:: The latest version number of a SIF file this library can process.

int sif_is_consolidate_set ( sif_file * file )

Return whether the file will be scheduled for consolidation on its close. Used blocks are moved toward the begining of the file, taking up the space of unused blocks before them. If there are no unused blocks or all of the unused blocks are at the end of the file, this file is simply truncated at the location of the first byte of the unused block and the meta-data is rewritten.

Parameters:

file

The file to check.

Returns:: The value of the consolidation flag.

See also:

sif_unset_consolidate

sif_set_consolidate

sif_consolidate

sif_close

sif_header::consolidate

int sif_is_defragment_set ( sif_file * file )

Unsets the defragmentation flag.

This cancels defragmentation when the file is closed.

Parameters:

file

The file to change.

Returns:: The value of the defragmentation flag.

See also:

sif_header::defragment

int sif_is_intrinsic_write_set ( sif_file * file )

Return the value of the uniformity flag. When true, a uniformity check is perfomed on all dirty tiles during close.

Parameters:

file

The file to check.

See also:

sif_unset_intrinsic_write

sif_is_intrinsic_write_set

sif_is_shallow_uniform

sif_is_slice_shallow_uniform

Returns:: The value of the flag.

int sif_is_possibly_sif_file ( const char * filename )

Returns a positive value if the file referred to by filename could possibly be a SIF file.

Parameters:

filename

The filename of the file to check.

Returns:: A boolean indicating the result of the check.

int sif_is_shallow_uniform	(	sif_file *	file,
		long	x,
		long	y,
		long	w,
		long	h,
		long	band,
		void *	uniform_value
	)

Determine if the tiles comprising a region are shallow uniform.

Parameters:

	file	The file to perform the check.
	x	The starting horizontal pixel offset (0..N-1 indexed) of the region to check.
	y	The starting vertical pixel offset (0..N-1 indexed) of the region to check.
	w	The width of the region.to check.
	h	The height of the region to check.
	band	The band offset (0..N-1 indexed).
	uniform_value	This value is only meaningful when this function returns true (non-zero). It is expected that the pointer passed point to at least data_unit_size bytes. When the region is completely uniform, the uniform pixel value is stored here.

Returns:: 0 if the tiles are not shallow uniform or a memory allocation error occurred, otherwise a non-zero value.

int sif_is_sif_simple ( const char * filename )

Return if the file referred to by the filename conforms to the "simple" data type convention.

Parameters:

filename

The filename of the file on which to perform the operation.

Returns:: A non-zero value if the file referred to by the filename conforms to the "simple" data type convention. If the file could not be opened, -1 is returned.

int sif_is_simple ( sif_file * file )

Return if the file conforms to the "simple" data type convention.

Parameters:

file

The file on which to perform the operation.

Returns:: A non-zero value if the file conforms to the "simple" data type convention.

int sif_is_slice_shallow_uniform	(	sif_file *	file,
		long	tx,
		long	ty,
		long	band,
		void *	uniform_value
	)

Determine if a tile has shallow uniformity.

Parameters:

	file	The file to perform the check.
	tx	The horizontal tile index (0..N-1 indexed) of the region to check.
	ty	The vertical tile index (0..N-1 indexed) of the region to check.
	band	The band offset (0..N-1 indexed).
	uniform_value	This value is only meaningful when this function returns true (non-zero). It is expected that the pointer passed point to at least data_unit_size bytes. When the region is completely uniform, the uniform pixel value is stored here.

Returns:: 0 if the tiles are non-uniform or a memory allocation error occurred, otherwise a non-zero value.

sif_file* sif_open	(	const char *	filename,
		int	read_only
	)

Open a Sparse Image File (SIF) format file for reading or update.

Parameters:

	filename	The filename of the SIF file to open.
	read_only	A flag indicating whether to open as read-only (1) or update (0).

Returns:: A file structure containing all the constructs needed to manipulate the opened SIF file is returned. NULL is returned if an error occured during open.

void sif_remove_meta_data_item	(	sif_file *	file,
		const char *	key
	)

Removes a meta-data item by its key string.

Parameters:

	file	The file from which to remove a meta-data item.
	key	The key of the meta-data item to remove.

void sif_set_affine_geo_transform	(	sif_file *	file,
		const double *	trans
	)

Set the affine georeferencing transform of an open file.

Parameters:

	file	The file to set the affine georeferencing transform.
	trans	A double array of size 6 with the new value of the georeferencing transform.

See also:: sif_get_affine_geo_transform
sif_header::affine_geo_transform

void sif_set_agreement	(	sif_file *	file,
		const char *	agree
	)

Set a string indicating the data type convention used in this file. If the string is "gdal" then the GDT type codes in the GDAL library are used. If the string is "simple" then the convention presented earlier in this document is used.

Parameters:

	file	The file to set the projection string.
	agree	The new projection string value.

See also:: sif_get_agreement

void sif_set_consolidate ( sif_file * file )

Set the consolidation flag.

Consolidation is then performed during the files close.

Parameters:

file

The file to change.

See also:

sif_unset_consolidate

sif_is_consolidate_set

sif_consolidate

sif_close

sif_header::consolidate

void sif_set_defragment ( sif_file * file )

Set the defragmentation flag.

Defragmentation is then performed during the file's close. Data blocks are rearranged in the order they appear in the image.

Parameters:

file

The file to change.

See also:: sif_unset_defragment
sif_is_defragment_set

void sif_set_intrinsic_write ( sif_file * file )

Set the uniformity flag. This results in a pixel uniformity check on all dirty tiles.

Parameters:

file

The file to change.

See also:

sif_is_intrinsic_write_set

sif_unset_intrinsic_write

sif_is_shallow_uniform

sif_is_slice_shallow_uniform

void sif_set_meta_data	(	sif_file *	file,
		const char *	key,
		const char *	value
	)

Set a meta-data field with a given key to a value defined by a null-terminated character string.

Parameters:

	file	The file to set the meta-data.
	key	The key of the field to set.
	value	The value to set the field.

See also:

sif_set_meta_data_binary

sif_get_meta_data

sif_get_meta_data_binary

void sif_set_meta_data_binary	(	sif_file *	file,
		const char *	key,
		const void *	buffer,
		int	n_bytes
	)

Set a meta-data field with a given key to a given sequence of bytes.

The length of the value is passed here, thereby allowing for binary, non-null-terminated, meta-data.

Parameters:

	file	The file on which to set the meta-data field.
	key	The key of the field to set.
	buffer	The value to set the field.
	n_bytes	The length of the value (in bytes).

Warning:: The meta-data is not written to the file until the file is closed or flushed.

See also:

sif_set_meta_data

sif_get_meta_data

sif_get_meta_data_binary

void sif_set_projection	(	sif_file *	file,
		const char *	proj
	)

Set the projection string of an open file. This is expected to be empty ("") or in OpenGIS WKT format. The string is stored in the "_sif_proj" field in the meta-data region of the file.

Parameters:

	file	The file to set the projection string.
	proj	The new projection string value.

See also:: sif_get_projection

void sif_set_raster	(	sif_file *	file,
		const void *	data,
		long	x,
		long	y,
		long	w,
		long	h,
		long	band
	)

Writes a rectangular image region to a file.

The tiles changed by this write are not checked for pixel uniformity. This results in the dirty flags in their respective tile headers being set to true. This results in a uniformity check during the file's close unless the uniformity check flag is set to false in the file's header. Also, any fragmentation caused by this function is not resolved until the file is closed.

Warning:: This function has not been tested.

Parameters:

	file	The file on which to write the raster plane.
	data	The buffer containing the raster to write.
	x	The starting horizontal pixel offset (0..N-1 indexed) to write.
	y	The starting vertical pixel offset (0..N-1 indexed) to write.
	w	The width of the region.
	h	The height of the region.
	band	The band offset (0..N-1 indexed).

See also:

sif_get_raster

sif_get_tile_slice

sif_set_tile_slice

void sif_set_tile_slice	(	sif_file *	file,
		const void *	buffer,
		long	tx,
		long	ty,
		long	band
	)

Store a tile slice.

A check is not made to determine pixel uniformity. The tile's dirty flag is set to true. This results in a uniformity check during the file's close, unless uniformity check flag is disabled in the file's header. Also, any fragmentation caused by this function is not resolved until the file is closed.

Parameters:

	file	The file on which to perform the write.
	tx	The horizontal index (0..N-1 indexed) of the slice to write.
	ty	The vertical index (0..N-1 indexed) of the slice to write.
	band	The band index (0..N-1 indexed) of the slice to write.
	buffer	The buffer to write. It must have enough bytes for an entire tile slice, e.g. sif_header::tile_width * sif_header::tile_height * sif_header::data_unit_size.

void sif_set_user_data_type	(	sif_file *	file,
		long	user_data_type
	)

Set the user data type for the file.

This value does not change the behavior of any sif-io functions. The user may use it to store an integer representing the data type of the pixel values in the image.

Parameters:

	file	The file to change the data type flag.
	user_data_type	The value of the new user-defined data type flag.

sif_file* sif_simple_create	(	const char *	filename,
		long	width,
		long	height,
		long	bands,
		int	simple_data_type,
		int	consolidate_on_close,
		int	defragment_on_close,
		long	tile_width,
		long	tile_height,
		int	intrinsic_write
	)

Create a new Sparse Image Format (SIF) file with a given filename and attributes. The file's header and tile headers are written. No space is preallocated for data blocks. The simple data-type convention is used. When reading, writing, or filling the image file created by this function, the sif_simple_* functions must be used to ensure the image data elements are written with the proper byte order.

Unless sif_simple_set_endian is called prior to reading or writing any image raster, the pixels will be stored in native byte order.

Parameters:

	filename	The filename of the new file.
	width	The width of the image to store in the file to create.
	height	The height of the image to store in the file to create.
	bands	The number of bands of the image to store in the file to create.
	simple_data_type	The data type code.
	tile_width	The width of a single tile.
	tile_height	The height of a single tile.
	consolidate_on_close	Defines whether a pixel uniformity check should be applied to dirty tiles during each close.
	defragment_on_close	Defines whether the file should be defragmented during each close.
	intrinsic_write	Defines whether intrinsic uniformity checks should be performed when rasters are written to a file.

Returns:: A file structure containing the constructs needed to manipulate the file created by this function. This function returns NULL if an error occurs during creation.

sif_file* sif_simple_create_defaults	(	const char *	filename,
		long	width,
		long	height,
		long	bands,
		int	simple_data_type
	)

When reading, writing, or filling the image file created by this function, the sif_simple_* functions must be used to ensure the image data elements are written with the proper byte order.

Unless sif_simple_set_endian is called prior to reading or writing any image raster, the pixels will be stored in native byte order.

The sif_header::consolidate, sif_header::defragment and the sif_header::intrisic_write flags are all set to true. The sif_header::tile_width and sif_header::tile_height are both set to 64.

Parameters:

	filename	The filename of the new file.
	width	The width of the image to store in the file to create.
	height	The height of the image to store in the file to create.
	bands	The number of bands of the image to store in the file to create.
	simple_data_type	The data type code.

Returns:: A file structure containing the constructs needed to manipulate the file created by this function. This function returns NULL if an error occurs during creation.

void sif_simple_fill_tile_slice	(	sif_file *	file,
		long	tx,
		long	ty,
		long	band,
		const void *	value
	)

Fill a tile slice with a constant value. The value is converted from host order to the byte order in the file.

Parameters:

	file	The file on which to perform the operation.
	tx	The horizontal index of the tile slice.
	ty	The vertical index of the tile slice.
	band	The band of the tile to which the slice corresponds.
	value	The pointer to the value to fill the tile slice.

void sif_simple_fill_tiles	(	sif_file *	file,
		long	band,
		const void *	value
	)

Fill a band with a constant value. The byte order of the value is converted to the byte order of the file's image.

Parameters:

	file	The file on which to perform the operation.
	band	The band to fill.
	value	The pointer to the value with which to fill the band.

int sif_simple_get_data_type ( sif_file * file )

Get the simple data type code of the pixel values in the image of this file.

Parameters:

file

The file on which to perform the operation.

Returns:: The simple data type code of the pixel values.

See also:: Simple Data Type Convention Macro Definitions

int sif_simple_get_endian ( sif_file * file )

Get the network byte order of the pixel values in the image of this file.

Parameters:

file

The file on which to perform the operation.

Returns:: The endian code of this file.

void sif_simple_get_raster	(	sif_file *	file,
		void *	data,
		long	x,
		long	y,
		long	w,
		long	h,
		long	band
	)

Read a rectangular region from a file. The byte order of the data values in the buffer is automatically converted to the byte order of the file.

Parameters:

	file	The file on which to perform the operation.
	data	The buffer into which the data will be read.
	x	The horizontal starting index of the file.
	y	The vertical starting index of the file.
	w	The width of the region.
	h	The height of the region.
	band	The band of the region.

void sif_simple_get_tile_slice	(	sif_file *	file,
		void *	buffer,
		long	tx,
		long	ty,
		long	band
	)

Retrieve a tile slice. The byte order of the data values in the buffer are in host byte order.

Parameters:

	file	The file on which to perform the operation.
	buffer	The buffer to store the slice.
	tx	The horizontal index of the tile slice.
	ty	The vertical index of the tile slice.
	band	The band of the tile to which the slice corresponds.

int sif_simple_is_shallow_uniform	(	sif_file *	file,
		long	x,
		long	y,
		long	w,
		long	h,
		long	band,
		void *	uniform_value
	)

Determine if the tiles comprising a region are shallow uniform. The "simple" data-type convention is assumed.

Parameters:

	file	The file to perform the check.
	x	The starting horizontal pixel offset (0..N-1 indexed) of the region to check.
	y	The starting vertical pixel offset (0..N-1 indexed) of the region to check.
	w	The width of the region.to check.
	h	The height of the region to check.
	band	The band offset (0..N-1 indexed).
	uniform_value	This value is only meaningful when this function returns true (non-zero). It is expected that the pointer passed point to at least data_unit_size bytes. When the region is completely uniform, the uniform pixel value is stored here.

Returns:: 0 if the tiles are not shallow uniform or a memory allocation error occurred, otherwise a non-zero value.

int sif_simple_is_slice_shallow_uniform	(	sif_file *	file,
		long	tx,
		long	ty,
		long	band,
		void *	uniform_value
	)

Determine if a tile slice has shallow uniformity. The simple user data type convention is assumed.

Parameters:

	file	The file to perform the check.
	tx	The horizontal tile index (0..N-1 indexed) of the region to check.
	ty	The vertical tile index (0..N-1 indexed) of the region to check.
	band	The band offset (0..N-1 indexed).
	uniform_value	This value is only meaningful when this function returns true (non-zero). It is expected that the pointer passed point to at least data_unit_size bytes. When the region is completely uniform, the uniform pixel value is stored here.

Returns:: 0 if the tiles are non-uniform or a memory allocation error occurred, otherwise a non-zero value.

sif_file* sif_simple_open	(	const char *	filename,
		int	read_only
	)

Open a Sparse Image File (SIF) format file for reading or update. The file is expected to use the Simple data type convention.

When reading, writing, or filling the image file opened by this function, the sif_simple_* functions must be used to ensure the image data elements are written with the proper byte order.

If the file does not use the simple data-type convention, 0 is returned.

Parameters:

	filename	The filename of the SIF file to open.
	read_only	A flag indicating whether to open as read-only (1) or update (0).

Returns:: A file structure containing all the constructs needed to manipulate the opened SIF file is returned. NULL is returned if an error occured during open.

void sif_simple_set_data_type	(	sif_file *	file,
		int	code
	)

Set the simple data type code for the pixel. Note that this field should never be set once a raster is written to a file.

Parameters:

	file	The file on which to perform the operation.
	code	The simple data type code of the pixel values.

See also:: Simple Data Type Convention Macro Definitions

void sif_simple_set_endian	(	sif_file *	file,
		int	endian
	)

Set the network byte order for the pixel. Note that this field should never be set once a raster is written to a file. This field must be set to one of SIF_SIMPLE_LITTLE_ENDIAN or SIF_SIMPLE_BIG_ENDIAN.

Parameters:

	file	The file on which to perform the operation.
	endian	The endian code to set the file.

void sif_simple_set_raster	(	sif_file *	file,
		const void *	data,
		long	x,
		long	y,
		long	w,
		long	h,
		long	band
	)

Write a rectangular region to a file. The byte order of the data values is automatically converted from host order to the the byte order of the file.

Parameters:

	file	The file on which to perform the operation.
	data	The buffer containing the data to write.
	x	The horizontal starting index of the file.
	y	The vertical starting index of the file.
	w	The width of the region.
	h	The height of the region.
	band	The band of the region.

void sif_simple_set_tile_slice	(	sif_file *	file,
		const void *	buffer,
		long	tx,
		long	ty,
		long	band
	)

Store a tile slice. The byte order of the data values in the buffer are converted to the byte order of the file.

Parameters:

	file	The file on which to perform the operation.
	buffer	The buffer to store the slice.
	tx	The horizontal index of the tile slice.
	ty	The vertical index of the tile slice.
	band	The band of the tile to which the slice corresponds.

void sif_unset_consolidate ( sif_file * file )

Unset the consolidation flag.

Consolidation is then performed during the files close.

Parameters:

file

The file to change.

See also:

sif_set_consolidate

sif_is_consolidate_set

sif_consolidate

sif_close

sif_header::consolidate

void sif_unset_defragment ( sif_file * file )

Set the defragmentation flag.

Defragmentation on the file's close is cancelled.

Parameters:

file

The file to change.

See also:

sif_set_defragment

sif_is_defragment_set

sif_defragment

sif_close

sif_header::defragment

void sif_unset_intrinsic_write ( sif_file * file )

Unset the uniformity flag.

This cancels pixel uniformity checks during close.

Parameters:

file

The file to change.

See also:

sif_unset_intrinsic_write

sif_set_intrinsic_write

sif_is_shallow_uniform

sif_is_slice_shallow_uniform

void sif_use_file_format_version	(	sif_file *	file,
		long	version
	)

Specifies that when the file is written, the file should be written with using the SIF file format version specified. If the version is not supported for write, a SIF_ERROR_CANNOT_WRITE_VERSION error is set in the header's error code field.

sif-io.h File Reference

Data Structures

Defines

Functions

Detailed Description

Define Documentation

Function Documentation