kealib::KEAImageIO Class Reference

#include <KEAImageIO.h>

Inheritance diagram for kealib::KEAImageIO:

Public Member Functions
	KEAImageIO ()
void	openKEAImageHeader (HighFive::File *keaImgH5File)
void	writeImageBlock2Band (uint32_t band, void *data, uint64_t xPxlOff, uint64_t yPxlOff, uint64_t xSizeOut, uint64_t ySizeOut, uint64_t xSizeBuf, uint64_t ySizeBuf, KEADataType inDataType)
void	readImageBlock2Band (uint32_t band, void *data, uint64_t xPxlOff, uint64_t yPxlOff, uint64_t xSizeIn, uint64_t ySizeIn, uint64_t xSizeBuf, uint64_t ySizeBuf, KEADataType inDataType)
void	createMask (uint32_t band, uint32_t deflate=KEA_DEFLATE)
void	writeImageBlock2BandMask (uint32_t band, void *data, uint64_t xPxlOff, uint64_t yPxlOff, uint64_t xSizeOut, uint64_t ySizeOut, uint64_t xSizeBuf, uint64_t ySizeBuf, KEADataType inDataType)
void	readImageBlock2BandMask (uint32_t band, void *data, uint64_t xPxlOff, uint64_t yPxlOff, uint64_t xSizeIn, uint64_t ySizeIn, uint64_t xSizeBuf, uint64_t ySizeBuf, KEADataType inDataType)
bool	maskCreated (uint32_t band)
void	setImageMetaData (const std::string &name, const std::string &value)
std::string	getImageMetaData (const std::string &name)
std::vector< std::string >	getImageMetaDataNames ()
std::vector< std::pair< std::string, std::string > >	getImageMetaData ()
void	setImageMetaData (const std::vector< std::pair< std::string, std::string > > &data)
void	setImageBandMetaData (uint32_t band, const std::string &name, const std::string &value)
std::string	getImageBandMetaData (uint32_t band, const std::string &name)
std::vector< std::string >	getImageBandMetaDataNames (uint32_t band)
std::vector< std::pair< std::string, std::string > >	getImageBandMetaData (uint32_t band)
void	setImageBandMetaData (uint32_t band, const std::vector< std::pair< std::string, std::string > > &data)
void	setImageBandDescription (uint32_t band, const std::string &description)
std::string	getImageBandDescription (uint32_t band)
void	setNoDataValue (uint32_t band, const void *data, KEADataType inDataType)
void	getNoDataValue (uint32_t band, void *data, KEADataType inDataType)
void	undefineNoDataValue (uint32_t band)
std::vector< KEAImageGCP * > *	getGCPs ()
void	setGCPs (std::vector< KEAImageGCP * > *gcps, const std::string &projWKT)
uint32_t	getGCPCount ()
std::string	getGCPProjection ()
void	setGCPProjection (const std::string &projWKT)
void	setSpatialInfo (KEAImageSpatialInfo *spatialInfo)
KEAImageSpatialInfo *	getSpatialInfo ()
uint32_t	getNumOfImageBands ()
uint32_t	getImageBlockSize (uint32_t band)
KEADataType	getImageBandDataType (uint32_t band)
std::string	getKEAImageVersion ()
void	setImageBandLayerType (uint32_t band, KEALayerType imgLayerType)
KEALayerType	getImageBandLayerType (uint32_t band)
void	setImageBandClrInterp (uint32_t band, KEABandClrInterp imgLayerClrInterp)
KEABandClrInterp	getImageBandClrInterp (uint32_t band)
void	createOverview (uint32_t band, uint32_t overview, uint64_t xSize, uint64_t ySize)
void	removeOverview (uint32_t band, uint32_t overview)
uint32_t	getOverviewBlockSize (uint32_t band, uint32_t overview)
void	writeToOverview (uint32_t band, uint32_t overview, void *data, uint64_t xPxlOff, uint64_t yPxlOff, uint64_t xSizeOut, uint64_t ySizeOut, uint64_t xSizeBuf, uint64_t ySizeBuf, KEADataType inDataType)
void	readFromOverview (uint32_t band, uint32_t overview, void *data, uint64_t xPxlOff, uint64_t yPxlOff, uint64_t xSizeIn, uint64_t ySizeIn, uint64_t xSizeBuf, uint64_t ySizeBuf, KEADataType inDataType)
uint32_t	getNumOfOverviews (uint32_t band)
void	getOverviewSize (uint32_t band, uint32_t overview, uint64_t *xSize, uint64_t *ySize)
KEAAttributeTable *	getAttributeTable (KEAATTType type, uint32_t band)
void	setAttributeTable (KEAAttributeTable *att, uint32_t band, uint32_t chunkSize=KEA_ATT_CHUNK_SIZE, uint32_t deflate=KEA_DEFLATE)
bool	attributeTablePresent (uint32_t band)
uint32_t	getAttributeTableChunkSize (uint32_t band)
void	close ()
virtual void	addImageBand (const KEADataType dataType, const std::string &bandDescrip, const uint32_t imageBlockSize=KEA_IMAGE_CHUNK_SIZE, const uint32_t attBlockSize=KEA_ATT_CHUNK_SIZE, const uint32_t deflate=KEA_DEFLATE)
virtual void	removeImageBand (const uint32_t bandIndex)
virtual	~KEAImageIO ()
Public Member Functions inherited from kealib::KEABase
	KEABase ()
	KEABase (const std::shared_ptr< kea_mutex > &other)

Static Public Member Functions
static HighFive::File *	createKEAImage (const std::string &fileName, KEADataType dataType, uint32_t xSize, uint32_t ySize, uint32_t numImgBands, std::vector< std::string > *bandDescrips=NULL, KEAImageSpatialInfo *spatialInfo=NULL, uint32_t imageBlockSize=KEA_IMAGE_CHUNK_SIZE, uint32_t attBlockSize=KEA_ATT_CHUNK_SIZE, int mdcElmts=KEA_MDC_NELMTS, hsize_t rdccNElmts=KEA_RDCC_NELMTS, hsize_t rdccNBytes=KEA_RDCC_NBYTES, double rdccW0=KEA_RDCC_W0, hsize_t sieveBuf=KEA_SIEVE_BUF, hsize_t metaBlockSize=KEA_META_BLOCKSIZE, uint32_t deflate=KEA_DEFLATE)
static bool	isKEAImage (const std::string &fileName)
static HighFive::File *	openKeaH5RW (const std::string &fileName, int mdcElmts=KEA_MDC_NELMTS, hsize_t rdccNElmts=KEA_RDCC_NELMTS, hsize_t rdccNBytes=KEA_RDCC_NBYTES, double rdccW0=KEA_RDCC_W0, hsize_t sieveBuf=KEA_SIEVE_BUF, hsize_t metaBlockSize=KEA_META_BLOCKSIZE)
static HighFive::File *	openKeaH5RDOnly (const std::string &fileName, int mdcElmts=KEA_MDC_NELMTS, hsize_t rdccNElmts=KEA_RDCC_NELMTS, hsize_t rdccNBytes=KEA_RDCC_NBYTES, double rdccW0=KEA_RDCC_W0, hsize_t sieveBuf=KEA_SIEVE_BUF, hsize_t metaBlockSize=KEA_META_BLOCKSIZE, hid_t driver_id=0, const void *driver_info=nullptr)
static HighFive::CompoundType	createGCPCompType ()

Protected Member Functions
void	readImageFromDataset (const HighFive::DataSet &dataset, uint32_t band, void *data, uint64_t xPxlOff, uint64_t yPxlOff, uint64_t xSizeIn, uint64_t ySizeIn, uint64_t xSizeBuf, uint64_t ySizeBuf, KEADataType inDataType, bool ismask=false)
void	writeImageToDataset (HighFive::DataSet &dataset, void *data, uint64_t xPxlOff, uint64_t yPxlOff, uint64_t xSizeOut, uint64_t ySizeOut, uint64_t xSizeBuf, uint64_t ySizeBuf, KEADataType inDataType)

Static Protected Member Functions
static HighFive::DataType	convertDatatypeKeaToH5STD (const KEADataType dataType)
static HighFive::DataType	convertDatatypeKeaToH5Native (const KEADataType dataType)
static const std::string	convertDatatypeKeaToCStdStr (const KEADataType dataType)
static void	addImageBandToFile (HighFive::File *keaImgH5File, const KEADataType dataType, const uint32_t xSize, const uint32_t ySize, const uint32_t bandIndex, const std::string &bandDescrip, const uint32_t imageBlockSize, const uint32_t attBlockSize, const uint32_t deflate)
static void	removeImageBandFromFile (HighFive::File *keaImgH5File, const uint32_t bandIndex, const uint32_t numImgBands)
static void	setNumImgBandsInFileMetadata (HighFive::File *keaImgH5File, const uint32_t numImgBands)

Protected Attributes
bool	fileOpen
HighFive::File *	keaImgFile
KEAImageSpatialInfo *	spatialInfoFile
uint32_t	numImgBands
std::string	keaVersion
Protected Attributes inherited from kealib::KEABase
std::shared_ptr< kea_mutex >	m_mutex

Constructor & Destructor Documentation

KEAImageIO()

kealib::KEAImageIO::KEAImageIO

(

)

~KEAImageIO()

virtual kealib::KEAImageIO::~KEAImageIO ( )

virtual

Member Function Documentation

addImageBand()

virtual void kealib::KEAImageIO::addImageBand ( const KEADataType  dataType, const std::string &  bandDescrip, const uint32_t  imageBlockSize = KEA_IMAGE_CHUNK_SIZE, const uint32_t  attBlockSize = KEA_ATT_CHUNK_SIZE, const uint32_t  deflate = KEA_DEFLATE  )

virtual

Adds a new image band to the KEA image file.

This method creates a new image band with the specified data type, description, and block sizes, and appends it to the KEA file. It updates the number of image bands in the file's metadata and ensures the new band is properly added and initialized.

Parameters

dataType	The data type of the new image band (e.g., integer, float, etc.).
bandDescrip	A description of the new image band, typically used as metadata.
imageBlockSize	The block size used for storing the image data in the file.
attBlockSize	The block size used for storing the attribute table data in the file.
deflate	ThebandDescripIn compression level (0 for no compression, higher values for increasing compression).

Exceptions

KEAIOException

If the image file is not open or issues occur during the band addition process.

addImageBandToFile()

static void kealib::KEAImageIO::addImageBandToFile ( HighFive::File *  keaImgH5File, const KEADataType  dataType, const uint32_t  xSize, const uint32_t  ySize, const uint32_t  bandIndex, const std::string &  bandDescrip, const uint32_t  imageBlockSize, const uint32_t  attBlockSize, const uint32_t  deflate  )

staticprotected

Adds a new image band to the specified KEA image file with the given parameters.

This method creates a new HDF5 group and datasets within the KEA image file to represent an image band. Metadata and attributes such as the band description, block size, data type, band type, band usage, and other properties are also initialized. The method ensures proper dataset and attribute creation while supporting compression and chunking for efficient storage. Does NOT flush the buffer

Parameters

keaImgH5File	A pointer to the HighFive::File object representing the open KEA image file.
dataType	The data type for the image data within the band, specified as a KEADataType.
xSize	The width of the image band in pixels.
ySize	The height of the image band in pixels.
bandIndex	The 1-based index of the band being added to the file.
bandDescrip	An optional description of the band. If empty, a default name is used.
imageBlockSize	The block size to use for chunking the image data. Adjusted if exceeding minimum dimension.
attBlockSize	The block size to use for attribute table chunking.
deflate	The compression level to use for deflating data (0-9, where higher values indicate stronger compression).

Exceptions

KEAIOException

If an error occurs while creating groups/datasets, writing attributes, or accessing metadata.

attributeTablePresent()

bool kealib::KEAImageIO::attributeTablePresent

(

uint32_t

band

)

Check whether an attriute table is present for an image band

Parameters

band	1-based index of image band

Exceptions

KEAIOException

close()

void kealib::KEAImageIO::close

(

)

Close file and flush all buffers

Exceptions

KEAIOException

convertDatatypeKeaToCStdStr()

static const std::string kealib::KEAImageIO::convertDatatypeKeaToCStdStr ( const KEADataType  dataType )

staticprotected

Converts a KEA image data type to its equivalent C++ standard string.

This method maps KEA-specific data types to their corresponding standardized C++ string representation of primitive or numerical data types.

Parameters

dataType

The KEADataType enumeration value representing the data type in the KEA image format that needs to be converted.

Returns

A string representation of the C++ data type corresponding to the provided KEADataType value.

Exceptions

KEAIOException

If the provided KEADataType is not recognized or cannot be mapped to a compatible C++ data type.

convertDatatypeKeaToH5Native()

static HighFive::DataType kealib::KEAImageIO::convertDatatypeKeaToH5Native ( const KEADataType  dataType )

staticprotected

Converts a KEA data type to the corresponding HDF5 native data type.

This method translates the specified KEADataType to its equivalent HighFive::DataType, enabling compatibility with HDF5 storage requirements. An exception is thrown if the provided KEA data type is not recognized or supported.

Parameters

dataType

The KEADataType to be converted. This should correspond to one of the predefined KEA data types, such as kea_8int, kea_16uint, kea_32float, etc.

Returns

The HighFive::DataType corresponding to the input KEADataType.

Exceptions

KEAIOException

If the specified data type is not recognized as a valid KEA data type.

convertDatatypeKeaToH5STD()

static HighFive::DataType kealib::KEAImageIO::convertDatatypeKeaToH5STD ( const KEADataType  dataType )

staticprotected

Converts a KEA data type to the corresponding HDF5 standard data type.

This method maps KEA-specific data types, represented by the KEADataType enumeration, to their equivalent HDF5 standard data types for usage within HDF5 data structures. Supported KEA data types include various integer, unsigned integer, and floating-point types. If an unrecognized data type is provided as input, an exception is thrown.

Parameters

dataType

The KEADataType value representing the KEA data type to be converted.

Returns

A HighFive::DataType object corresponding to the equivalent HDF5 standard data type for the given KEA data type.

Exceptions

KEAIOException

If the specified data type is not recognized among the defined KEA data types.

createGCPCompType()

static HighFive::CompoundType kealib::KEAImageIO::createGCPCompType ( )

static

Helper method to get a HighFive::CompoundType for the GCP data type

Exceptions

KEAIOException

createKEAImage()

static HighFive::File * kealib::KEAImageIO::createKEAImage ( const std::string &  fileName, KEADataType  dataType, uint32_t  xSize, uint32_t  ySize, uint32_t  numImgBands, std::vector< std::string > *  bandDescrips = NULL, KEAImageSpatialInfo *  spatialInfo = NULL, uint32_t  imageBlockSize = KEA_IMAGE_CHUNK_SIZE, uint32_t  attBlockSize = KEA_ATT_CHUNK_SIZE, int  mdcElmts = KEA_MDC_NELMTS, hsize_t  rdccNElmts = KEA_RDCC_NELMTS, hsize_t  rdccNBytes = KEA_RDCC_NBYTES, double  rdccW0 = KEA_RDCC_W0, hsize_t  sieveBuf = KEA_SIEVE_BUF, hsize_t  metaBlockSize = KEA_META_BLOCKSIZE, uint32_t  deflate = KEA_DEFLATE  )

static

Creates a new KEA image file and initializes its spatial metadata, global headers, global metadata, ground control points (GCPs), and specified image bands.

This method constructs a HighFive::File object for the KEA image file, populates its headers with spatial information, file metadata, and other required attributes. It also creates the requested number of image bands and their associated datasets. Spatial information and metadata such as top-left coordinates, pixel resolution, rotation, and coordinate reference system can be specified or initialized with default values.

Parameters

fileName	The name of the KEA image file to be created.
dataType	Data type of the image bands (e.g., integer, float).
xSize	The number of pixels along the X (horizontal) dimension of the image.
ySize	The number of pixels along the Y (vertical) dimension of the image.
numImgBands	The number of image bands to create in the KEA file.
bandDescrips	Optional vector containing descriptions for each band. If null, bands will have empty descriptions.
spatialInfo	Optional pointer to KEAImageSpatialInfo containing spatial metadata to be written to the file. If null, default values will be used.
imageBlockSize	The block size for dividing image band data into tiles.
attBlockSize	The block size for attribute data in the image bands.
mdcElmts	The number of metadata cache elements.
rdccNElmts	The number of elements in the raw data chunk cache.
rdccNBytes	The total size (in bytes) of the raw data chunk cache.
rdccW0	The policy for evicting raw data chunks from the cache.
sieveBuf	The size of the sieve buffer (in bytes).
metaBlockSize	The size (in bytes) of blocks allocated for metadata.
deflate	The compression level to use (0 = no compression, 9 = maximum compression).

Returns

A pointer to the created HighFive::File object representing the KEA image file.

Exceptions

KEAIOException	If an error occurs during file creation, writing metadata, or initializing content.
HighFive::Exception	If there is a failure within the HighFive library while creating or modifying the file.
std::exception	For any other uncaught errors that occur during processing.

createMask()

void kealib::KEAImageIO::createMask	(	uint32_t	band,
		uint32_t	deflate = KEA_DEFLATE
	)

Creates a mask band

This method creates a mask band for the specified band

Parameters

band	The band to create a mask band for. 1-based.
deflate	The level of compression to use

Exceptions

KEAIOException

If there is a problem creating the mask band

createOverview()

void kealib::KEAImageIO::createOverview	(	uint32_t	band,
		uint32_t	overview,
		uint64_t	xSize,
		uint64_t	ySize
	)

Create an overview for an image band

Parameters

band	1-based index of the image band
overview	0-based overview level to create
xSize	The X size of the overview in pixels
ySize	The X size of the overview in pixels

Exceptions

KEAIOException

getAttributeTable()

KEAAttributeTable * kealib::KEAImageIO::getAttributeTable	(	KEAATTType	type,
		uint32_t	band
	)

Get the attribute table for an image band

Parameters

type	Type of attribute table object to return - in mem or file
band	1-based index of image band

Exceptions

KEAIOException

getAttributeTableChunkSize()

uint32_t kealib::KEAImageIO::getAttributeTableChunkSize

(

uint32_t

band

)

Get the chunk size for the attribute table

Parameters

band	1-based index of image band

Exceptions

KEAIOException

getGCPCount()

uint32_t kealib::KEAImageIO::getGCPCount

(

)

Get the count of the GCPs saved for this image

Exceptions

KEAIOException

getGCPProjection()

std::string kealib::KEAImageIO::getGCPProjection

(

)

Get the projection of the saved CGPs as a WKT string

Exceptions

KEAIOException

getGCPs()

std::vector< KEAImageGCP * > * kealib::KEAImageIO::getGCPs

(

)

Get the GCPs for the image

Exceptions

KEAIOException

getImageBandClrInterp()

KEABandClrInterp kealib::KEAImageIO::getImageBandClrInterp

(

uint32_t

band

)

Get the colour interpretation for the image band

Parameters

band	1-based index of the band to get the colour interpretation

Exceptions

KEAIOException

getImageBandDataType()

KEADataType kealib::KEAImageIO::getImageBandDataType

(

uint32_t

band

)

Get the KEA data type for the specified band

Parameters

band	1-based index of the band

Exceptions

KEAIOException

getImageBandDescription()

std::string kealib::KEAImageIO::getImageBandDescription

(

uint32_t

band

)

Get the description of an image band as a string

Parameters

band	1-based index of the band to set description

Exceptions

KEAIOException

getImageBandLayerType()

KEALayerType kealib::KEAImageIO::getImageBandLayerType

(

uint32_t

band

)

Get the layer type (thematic or continuous) for the image band

Parameters

band	1-based index of the band to get the layer type for

Exceptions

KEAIOException

getImageBandMetaData() [1/2]

std::vector< std::pair< std::string, std::string > > kealib::KEAImageIO::getImageBandMetaData

(

uint32_t

band

)

Get all the band metadata names and values as a vector of pairs

Parameters

band	1-based index of the band to set metadata

Exceptions

KEAIOException

getImageBandMetaData() [2/2]

std::string kealib::KEAImageIO::getImageBandMetaData	(	uint32_t	band,
		const std::string &	name
	)

Get an band metadata value

Parameters

band	1-based index of the band to get metadata
name	The name of the metadata item to retrieve

Exceptions

KEAIOException

getImageBandMetaDataNames()

std::vector< std::string > kealib::KEAImageIO::getImageBandMetaDataNames

(

uint32_t

band

)

Get all the names of the band metadata items

Parameters

band	1-based index of the band to get metadata

Exceptions

KEAIOException

getImageBlockSize()

uint32_t kealib::KEAImageIO::getImageBlockSize

(

uint32_t

band

)

Retrieves the block size of an image band.

This method returns the block size for a specific band in the KEA image. The block size refers to the dimensions used for storing blocks of image data within a band.

Parameters

band	The band number for which the block size is to be retrieved. Band indexing starts at 1. Providing a value of 0 or greater than the total number of bands in the image will throw an exception.

Returns

The block size of the specified band as an unsigned 32-bit integer.

Exceptions

KEAIOException

If the image file is not open, the band index is invalid, the specific band dataset or block size attribute is missing, or if an error occurs while reading the necessary data.

getImageMetaData() [1/2]

std::vector< std::pair< std::string, std::string > > kealib::KEAImageIO::getImageMetaData

(

)

Get all the image metadata names and values as a vector of pairs

Exceptions

KEAIOException

getImageMetaData() [2/2]

std::string kealib::KEAImageIO::getImageMetaData

(

const std::string &

name

)

Get an image metadata value

Parameters

name	The name of the metadata item to retrieve

Exceptions

KEAIOException

getImageMetaDataNames()

std::vector< std::string > kealib::KEAImageIO::getImageMetaDataNames

(

)

Get all the names of the image metadata items

Exceptions

KEAIOException

getKEAImageVersion()

std::string kealib::KEAImageIO::getKEAImageVersion

(

)

Get the version of this KEA file

Exceptions

KEAIOException

if file not open

getNoDataValue()

void kealib::KEAImageIO::getNoDataValue	(	uint32_t	band,
		void *	data,
		KEADataType	inDataType
	)

Get the no data value for a band

Parameters

band	1-based index of the band to get the no data
data	pointer that receives the no data
inDataType	data type to read the no data as

Exceptions

KEAIOException

if the nodata has not been set for this band

getNumOfImageBands()

uint32_t kealib::KEAImageIO::getNumOfImageBands

(

)

Get the number of bands of this image

getNumOfOverviews()

uint32_t kealib::KEAImageIO::getNumOfOverviews

(

uint32_t

band

)

Get the number of overviews for an image band

Parameters

band	1-based index of image band

Exceptions

KEAIOException

getOverviewBlockSize()

uint32_t kealib::KEAImageIO::getOverviewBlockSize	(	uint32_t	band,
		uint32_t	overview
	)

Get the block size used for an overview

Parameters

band	1-based index of image band
overview	0-based overview level

Exceptions

KEAIOException

getOverviewSize()

void kealib::KEAImageIO::getOverviewSize	(	uint32_t	band,
		uint32_t	overview,
		uint64_t *	xSize,
		uint64_t *	ySize
	)

Get the size of an overview

Parameters

band	1-based index of image band
overview	0-based overview level
xSize	pointer to where the X size of the overview will be stored
ySize	pointer to where the Y size of the overview will be stored

Exceptions

KEAIOException

getSpatialInfo()

KEAImageSpatialInfo * kealib::KEAImageIO::getSpatialInfo

(

)

Get the spatial info for the dataset

isKEAImage()

static bool kealib::KEAImageIO::isKEAImage ( const std::string &  fileName )

static

Determines whether the specified file is a valid KEA image file.

This method checks the provided file to verify if it complies with the KEA file format by inspecting key datasets in the HDF5 structure, including the file type and version metadata. The file is validated as a KEA image if the file type dataset contains "KEA" and the version is one of the supported versions (e.g., "1.0" or "1.1").

Parameters

fileName

A string representing the path to the file being checked. The file must be accessible and of HDF5 format.

Returns

True if the file is verified as a KEA image, otherwise False.

Exceptions

KEAIOException

If the file cannot be opened, an error occurs during metadata reading, or a non-KEA related exception occurs.

maskCreated()

bool kealib::KEAImageIO::maskCreated

(

uint32_t

band

)

Determines whether a mask band has been created for the specified band

Parameters

band	The 1-based band number to check the existance of a mask band for

Exceptions

KEAIOException

openKeaH5RDOnly()

static HighFive::File * kealib::KEAImageIO::openKeaH5RDOnly ( const std::string &  fileName, int  mdcElmts = KEA_MDC_NELMTS, hsize_t  rdccNElmts = KEA_RDCC_NELMTS, hsize_t  rdccNBytes = KEA_RDCC_NBYTES, double  rdccW0 = KEA_RDCC_W0, hsize_t  sieveBuf = KEA_SIEVE_BUF, hsize_t  metaBlockSize = KEA_META_BLOCKSIZE, hid_t  driver_id = 0, const void *  driver_info = nullptr  )

static

Opens a KEA HDF5 image file in read-only mode and returns a pointer to the file object.

This method attempts to open the specified KEA image file in a read-only mode using the HighFive library. It initializes default file access properties and sets up the file structure while handling potential exceptions. File caching and property optimizations, such as metadata cache configuration or sieve buffer size, may be configured but are currently commented out.

Parameters

fileName	The path to the KEA HDF5 image file that needs to be opened.
mdcElmts	Number of elements in the metadata cache.
rdccNElmts	Number of elements in the raw data chunk cache.
rdccNBytes	Total size of the raw data chunk cache in bytes.
rdccW0	The preemption policy value for raw data chunk cache.
sieveBuf	Size of the data sieve buffer in bytes.
metaBlockSize	Size of the metadata block allocation in bytes.
driver_id	ID of HDF5 virtual filesystem driver
driver_info	a pointer to be passed to the virtual filesystem driver

Returns

A pointer to a HighFive::File object representing the opened KEA HDF5 image file. The file is opened in a read-only mode.

Exceptions

KEAIOException

If the file is not a valid KEA file, the file does not exist, or any error occurs while opening the file or initializing the file properties.

openKeaH5RW()

static HighFive::File * kealib::KEAImageIO::openKeaH5RW ( const std::string &  fileName, int  mdcElmts = KEA_MDC_NELMTS, hsize_t  rdccNElmts = KEA_RDCC_NELMTS, hsize_t  rdccNBytes = KEA_RDCC_NBYTES, double  rdccW0 = KEA_RDCC_W0, hsize_t  sieveBuf = KEA_SIEVE_BUF, hsize_t  metaBlockSize = KEA_META_BLOCKSIZE  )

static

Opens a KEA HDF5 file for read-write access and returns a pointer to the file object.

This method creates and initializes an instance of the HighFive::File class with read-write access mode. It optionally allows configuration of HDF5 file access properties, such as metadata cache settings, raw data chunk cache, and I/O performance parameters. If the file cannot be opened or any error occurs during initialization, this method throws an appropriate exception.

Parameters

fileName	The path to the KEA HDF5 file to be opened.
mdcElmts	The number of elements in the metadata cache.
rdccNElmts	The number of elements in the raw data chunk cache.
rdccNBytes	The total size, in bytes, of the raw data chunk cache.
rdccW0	The write mode fraction for the raw data chunk cache.
sieveBuf	The minimum size, in bytes, of the sieve buffer for data I/O.
metaBlockSize	The size, in bytes, of the metadata aggregation block.

Returns

A pointer to the HighFive::File object representing the opened KEA file with read-write access.

Exceptions

KEAIOException

If the file cannot be opened, does not exist, or any error occurs during the file initialization or access configuration.

openKEAImageHeader()

void kealib::KEAImageIO::openKEAImageHeader

(

HighFive::File *

keaImgH5File

)

Opens the header of the KEA image file and initializes relevant spatial and metadata attributes.

This method takes a pointer to a KEA HDF5 image file and reads the file's header information in order to initialize spatial metadata, such as the number of image bands, top-left coordinates, pixel resolution, image rotation, image size, and the spatial reference system in WKT format. The method also verifies the file type and format version to ensure compatibility.

Parameters

keaImgH5File

A pointer to the HighFive::File object representing the KEA image file. This file must be an open HDF5 file containing a valid KEA image structure.

Exceptions

KEAIOException

If the file is not a valid KEA file, required datasets are missing, or errors occur while reading any of the metadata attributes.

readFromOverview()

void kealib::KEAImageIO::readFromOverview	(	uint32_t	band,
		uint32_t	overview,
		void *	data,
		uint64_t	xPxlOff,
		uint64_t	yPxlOff,
		uint64_t	xSizeIn,
		uint64_t	ySizeIn,
		uint64_t	xSizeBuf,
		uint64_t	ySizeBuf,
		KEADataType	inDataType
	)

Read data from an overview

Parameters

band	1-based index of image band
overview	0-based overview level
data	A pointer to the buffer where the image data will be stored after reading. The buffer should have enough memory based on the subset size.
xPxlOff	The horizontal pixel offset in the image from which the subset begins.
yPxlOff	The vertical pixel offset in the image from which the subset begins.
xSizeIn	The width of the subset to read, starting from xPxlOff.
ySizeIn	The height of the subset to read, starting from yPxlOff.
xSizeBuf	The width of the provided buffer where the data will be stored.
ySizeBuf	The height of the provided buffer where the data will be stored.
inDataType	The data type of the pixel values specified as a KEADataType. This determines how to interpret the data while reading.

Exceptions

KEAIOException

readImageBlock2Band()

void kealib::KEAImageIO::readImageBlock2Band	(	uint32_t	band,
		void *	data,
		uint64_t	xPxlOff,
		uint64_t	yPxlOff,
		uint64_t	xSizeIn,
		uint64_t	ySizeIn,
		uint64_t	xSizeBuf,
		uint64_t	ySizeBuf,
		KEADataType	inDataType
	)

Reads a block of image data for a specified band from the KEA image file.

This method fetches a specified subset of image pixels for a particular band from the associated KEA image dataset and writes it to the provided buffer. The subset is defined by the spatial offsets and sizes. The method ensures the provided input parameters are valid and fall within the image dimensions. If the buffer size does not match the subset size, only the specified region within the image dimensions is processed.

Parameters

band	The band number to read from. Band numbers start at 1 and must not exceed the total number of bands in the image.
data	A pointer to the buffer where the image data will be stored after reading. The buffer should have enough memory based on the subset size.
xPxlOff	The horizontal pixel offset in the image from which the subset begins.
yPxlOff	The vertical pixel offset in the image from which the subset begins.
xSizeIn	The width of the subset to read, starting from xPxlOff.
ySizeIn	The height of the subset to read, starting from yPxlOff.
xSizeBuf	The width of the provided buffer where the data will be stored.
ySizeBuf	The height of the provided buffer where the data will be stored.
inDataType	The data type of the pixel values specified as a KEADataType. This determines how to interpret the data while reading.

Exceptions

KEAIOException	If the file is not open, if the band does not exist, if spatial offsets/sizes are out of bounds, or if the dataset does not exist.
HighFive::Exception	If there are any HDF5-related errors during the dataset operations.
std::exception	If any other unexpected errors are encountered.

readImageBlock2BandMask()

void kealib::KEAImageIO::readImageBlock2BandMask	(	uint32_t	band,
		void *	data,
		uint64_t	xPxlOff,
		uint64_t	yPxlOff,
		uint64_t	xSizeIn,
		uint64_t	ySizeIn,
		uint64_t	xSizeBuf,
		uint64_t	ySizeBuf,
		KEADataType	inDataType
	)

Reads data from the mask band

Once a mask band has been created with createMask(), use this method to read data from it.

Parameters

band	The band number with the mask band to read from. Band numbers start at 1 and must not exceed the total number of bands in the image.
data	A pointer to the buffer where the image data will be stored after reading. The buffer should have enough memory based on the subset size.
xPxlOff	The horizontal pixel offset in the image from which the subset begins.
yPxlOff	The vertical pixel offset in the image from which the subset begins.
xSizeIn	The width of the subset to read, starting from xPxlOff.
ySizeIn	The height of the subset to read, starting from yPxlOff.
xSizeBuf	The width of the provided buffer where the data will be stored.
ySizeBuf	The height of the provided buffer where the data will be stored.
inDataType	The data type of the pixel values specified as a KEADataType. This determines how to interpret the data while reading.

Exceptions

KEAIOException

readImageFromDataset()

void kealib::KEAImageIO::readImageFromDataset ( const HighFive::DataSet &  dataset, uint32_t  band, void *  data, uint64_t  xPxlOff, uint64_t  yPxlOff, uint64_t  xSizeIn, uint64_t  ySizeIn, uint64_t  xSizeBuf, uint64_t  ySizeBuf, KEADataType  inDataType, bool  ismask = false  )

protected

helper to read part of an image from a HDF5 dataset

This is an internal method designed to read imagery, overviews and masks out of an HighFive::DataSet object,

Parameters

dataset	A reference to a HighFive::DataSet containing imagery to read
band	1-based index of the image band to read
data	A pointer to the memory to read the data into
xPxlOff	The horizontal pixel offset in the image where the data block starts.
yPxlOff	The vertical pixel offset in the image where the data block starts.
xSizeIn	The horizontal size of the output image data block to be written.
ySizeIn	The vertical size of the output image data block to be written.
xSizeBuf	The horizontal size of the provided data buffer.
ySizeBuf	The vertical size of the provided data buffer.
inDataType	The data type of the input image data, specified using KEADataType.
ismask	A flag determining whether kealib should look for an ignore value - only done if !ismask

Exceptions

KEAIOException

If there is a problem reading from the dataset

removeImageBand()

virtual void kealib::KEAImageIO::removeImageBand ( const uint32_t  bandIndex )

virtual

Removes an image band from the KEA image file at the specified band index.

This method deletes a specific image band from the KEA file, decrements the total number of image bands, updates the band count in the file metadata, and flushes the changes to the file. If the image file is not open, an exception is thrown.

Parameters

bandIndex

The index of the image band to be removed. The index is 1-based.

Exceptions

KEAIOException

If the image file is not open, or if errors occur while removing the image band or updating the metadata.

removeImageBandFromFile()

static void kealib::KEAImageIO::removeImageBandFromFile ( HighFive::File *  keaImgH5File, const uint32_t  bandIndex, const uint32_t  numImgBands  )

staticprotected

Removes a specified image band from the KEA image file and renames the remaining bands.

This method deletes the dataset corresponding to the specified band index from the HDF5 file and shifts the remaining bands to close the gap in the sequential numbering. If the provided band index is invalid (i.e., less than 1 or greater than the total number of bands), an exception is thrown. It also handles potential exceptions from the HDF5 operations. Does NOT flush the buffer

Parameters

keaImgH5File	A pointer to the HighFive::File object representing the KEA image file. This file must have datasets corresponding to the image bands.
bandIndex	The index of the image band to be removed. The band index must be greater than or equal to 1 and less than or equal to the total number of image bands.
numImgBands	The total number of image bands currently present in the file.

Exceptions

KEAIOException

If the band index is invalid or any errors occur during the HDF5 file operations, such as unlinking or renaming datasets.

removeOverview()

void kealib::KEAImageIO::removeOverview	(	uint32_t	band,
		uint32_t	overview
	)

Remove an overview for an image band

Parameters

band	1-based index of the image band
overview	0-based overview level to remove

Exceptions

KEAIOException

setAttributeTable()

void kealib::KEAImageIO::setAttributeTable	(	KEAAttributeTable *	att,
		uint32_t	band,
		uint32_t	chunkSize = KEA_ATT_CHUNK_SIZE,
		uint32_t	deflate = KEA_DEFLATE
	)

Set an attribute table for an image band

Parameters

att	pointer to the attribute table object
band	1-based index of image band
chunkSize	checksize to use when writing the table
deflate	deflate level to use

Exceptions

KEAIOException

setGCPProjection()

void kealib::KEAImageIO::setGCPProjection

(

const std::string &

projWKT

)

Set the projection of the saved CGPs as a WKT string

Parameters

projWKT

a WKT string defining the projection

Exceptions

KEAIOException

setGCPs()

void kealib::KEAImageIO::setGCPs	(	std::vector< KEAImageGCP * > *	gcps,
		const std::string &	projWKT
	)

Set the GCPs for the image

Exceptions

KEAIOException

setImageBandClrInterp()

void kealib::KEAImageIO::setImageBandClrInterp	(	uint32_t	band,
		KEABandClrInterp	imgLayerClrInterp
	)

Set the colour interpretation for the image band

Parameters

band	1-based index of the band to set the colour interpretation
imgLayerClrInterp	the colur interpretation to set

Exceptions

KEAIOException

setImageBandDescription()

void kealib::KEAImageIO::setImageBandDescription	(	uint32_t	band,
		const std::string &	description
	)

Set the description of an image band to a string

Parameters

band	1-based index of the band to set description
description	string to set as the description

Exceptions

KEAIOException

setImageBandLayerType()

void kealib::KEAImageIO::setImageBandLayerType	(	uint32_t	band,
		KEALayerType	imgLayerType
	)

Set the layer type for an image band (thematic or continuous)

Parameters

band	1-based index of the band to set the layer type
imgLayerType	the layer type to set

Exceptions

KEAIOException

setImageBandMetaData() [1/2]

void kealib::KEAImageIO::setImageBandMetaData	(	uint32_t	band,
		const std::string &	name,
		const std::string &	value
	)

Set a band metadata value

Parameters

band	1-based index of the band to set metadata
name	The name of the metadata item to set
value	The value to set the metadata item to

Exceptions

KEAIOException

setImageBandMetaData() [2/2]

void kealib::KEAImageIO::setImageBandMetaData	(	uint32_t	band,
		const std::vector< std::pair< std::string, std::string > > &	data
	)

Set all the band metadata names and values at once

Parameters

band	1-based index of the band to set metadata
data	a vector of pairs describing the metadata

Exceptions

KEAIOException

setImageMetaData() [1/2]

void kealib::KEAImageIO::setImageMetaData	(	const std::string &	name,
		const std::string &	value
	)

Set an image metadata value

Parameters

name	The name of the metadata item to set
value	The value to set the metadata item to

Exceptions

KEAIOException

setImageMetaData() [2/2]

void kealib::KEAImageIO::setImageMetaData

(

const std::vector< std::pair< std::string, std::string > > &

data

)

Set all the image metadata names and values at once

Parameters

data	a vector of pairs describing the metadata

Exceptions

KEAIOException

setNoDataValue()

void kealib::KEAImageIO::setNoDataValue	(	uint32_t	band,
		const void *	data,
		KEADataType	inDataType
	)

Set the no data value for a band

Parameters

band	1-based index of the band to set the no data
data	pointer to the nodata value
inDataType	data type of the no data value passed

Exceptions

KEAIOException

setNumImgBandsInFileMetadata()

static void kealib::KEAImageIO::setNumImgBandsInFileMetadata ( HighFive::File *  keaImgH5File, const uint32_t  numImgBands  )

staticprotected

Updates or creates the metadata entry for the number of image bands in the KEA image file.

This method determines if the dataset corresponding to the number of image bands exists in the provided KEA HDF5 file. If it exists, the dataset is updated with the new value. Otherwise, a new dataset is created with the specified value. The method ensures the metadata is consistent and throws appropriate exceptions upon error. Does NOT flush the buffer

Parameters

keaImgH5File	A pointer to the HighFive::File object representing the KEA image file. This file must be an open HDF5 file capable of being read or written to.
numImgBands	The number of image bands to be set in the metadata. This value represents the updated or initial band count for the KEA file.

Exceptions

KEAIOException

If there is an issue reading or writing the dataset, the file structure is invalid, or any other lower-level library exception occurs.

setSpatialInfo()

void kealib::KEAImageIO::setSpatialInfo

(

KEAImageSpatialInfo *

spatialInfo

)

Set the spatial info for the dataset

Parameters

spatialInfo

a pointer to the spatial info struct to set for this dataset

Exceptions

KEAIOException

undefineNoDataValue()

void kealib::KEAImageIO::undefineNoDataValue

(

uint32_t

band

)

Unset the no data for a band

Parameters

band	1-based index of the band to unset the nodata

Exceptions

KEAIOException

if the nodata has not been set for this band

writeImageBlock2Band()

void kealib::KEAImageIO::writeImageBlock2Band	(	uint32_t	band,
		void *	data,
		uint64_t	xPxlOff,
		uint64_t	yPxlOff,
		uint64_t	xSizeOut,
		uint64_t	ySizeOut,
		uint64_t	xSizeBuf,
		uint64_t	ySizeBuf,
		KEADataType	inDataType
	)

Writes a block of image data to a specified band in the KEA image file.

This method handles the writing of image data to a specific band while ensuring that the specified pixel offsets, dimensions, and buffer sizes fit within the bounds of the image dimensions. It supports writing subsets or entire blocks of data depending on the provided parameters. Metadata integrity and dataset existence are also verified within this function.

Parameters

band	The one-based index of the band to which the data will be written. Band 1 is the first band.
data	A pointer to the memory containing the image data to be written.
xPxlOff	The horizontal pixel offset in the image where the data block starts.
yPxlOff	The vertical pixel offset in the image where the data block starts.
xSizeOut	The horizontal size of the output image data block to be written.
ySizeOut	The vertical size of the output image data block to be written.
xSizeBuf	The horizontal size of the provided data buffer.
ySizeBuf	The vertical size of the provided data buffer.
inDataType	The data type of the input image data, specified using KEADataType.

Exceptions

KEAIOException

If the file is not open, the band index is invalid, pixel offsets are outside the image bounds, or the band dataset does not exist. Other errors related to I/O operations or metadata issues are also reported via this exception.

writeImageBlock2BandMask()

void kealib::KEAImageIO::writeImageBlock2BandMask	(	uint32_t	band,
		void *	data,
		uint64_t	xPxlOff,
		uint64_t	yPxlOff,
		uint64_t	xSizeOut,
		uint64_t	ySizeOut,
		uint64_t	xSizeBuf,
		uint64_t	ySizeBuf,
		KEADataType	inDataType
	)

Writes data to the mask band

Once a mask band has been created with createMask(), use this method to write data to it.

Parameters

band	The one-based index of the band with the mask band to which the data will be written. Band 1 is the first band.
data	A pointer to the memory containing the image data to be written.
xPxlOff	The horizontal pixel offset in the image where the data block starts.
yPxlOff	The vertical pixel offset in the image where the data block starts.
xSizeOut	The horizontal size of the output image data block to be written.
ySizeOut	The vertical size of the output image data block to be written.
xSizeBuf	The horizontal size of the provided data buffer.
ySizeBuf	The vertical size of the provided data buffer.
inDataType	The data type of the input image data, specified using KEADataType.

Exceptions

KEAIOException

writeImageToDataset()

void kealib::KEAImageIO::writeImageToDataset ( HighFive::DataSet &  dataset, void *  data, uint64_t  xPxlOff, uint64_t  yPxlOff, uint64_t  xSizeOut, uint64_t  ySizeOut, uint64_t  xSizeBuf, uint64_t  ySizeBuf, KEADataType  inDataType  )

protected

helper to write part of an image form a HDF5 dataset

This is an internal method designed to read imagery, overviews and masks out of an HighFive::DataSet object,

Parameters

dataset	A reference to a HighFive::DataSet containing imagery to read
data	A pointer to the memory containing the image data to be written.
xPxlOff	The horizontal pixel offset in the image where the data block starts.
yPxlOff	The vertical pixel offset in the image where the data block starts.
xSizeOut	The horizontal size of the output image data block to be written.
ySizeOut	The vertical size of the output image data block to be written.
xSizeBuf	The horizontal size of the provided data buffer.
ySizeBuf	The vertical size of the provided data buffer.
inDataType	The data type of the input image data, specified using KEADataType.

Exceptions

KEAIOException

If there is a problem writing to the dataset

writeToOverview()

void kealib::KEAImageIO::writeToOverview	(	uint32_t	band,
		uint32_t	overview,
		void *	data,
		uint64_t	xPxlOff,
		uint64_t	yPxlOff,
		uint64_t	xSizeOut,
		uint64_t	ySizeOut,
		uint64_t	xSizeBuf,
		uint64_t	ySizeBuf,
		KEADataType	inDataType
	)

Write data to an overview

Parameters

band	1-based index of image band
overview	0-based overview level
data	A pointer to the memory containing the image data to be written.
xPxlOff	The horizontal pixel offset in the image where the data block starts.
yPxlOff	The vertical pixel offset in the image where the data block starts.
xSizeOut	The horizontal size of the output image data block to be written.
ySizeOut	The vertical size of the output image data block to be written.
xSizeBuf	The horizontal size of the provided data buffer.
ySizeBuf	The vertical size of the provided data buffer.
inDataType	The data type of the input image data, specified using KEADataType.

Exceptions

KEAIOException

Member Data Documentation

fileOpen

bool kealib::KEAImageIO::fileOpen

protected

keaImgFile

HighFive::File* kealib::KEAImageIO::keaImgFile

protected

keaVersion

std::string kealib::KEAImageIO::keaVersion

protected

numImgBands

uint32_t kealib::KEAImageIO::numImgBands

protected

spatialInfoFile

KEAImageSpatialInfo* kealib::KEAImageIO::spatialInfoFile

protected

---

The documentation for this class was generated from the following file:

• include/libkea/KEAImageIO.h