drwnImageCache Class Reference

Caches images in memory up to a maximum number of images or memory limit. More...

Public Member Functions
	drwnImageCache (bool bGreyImages=GREY_IMAGES, bool bBigMemory=BIG_MEMORY)
	constructor
	drwnImageCache (const vector< string > &filenames, bool bGreyImages=GREY_IMAGES, bool bBigMemory=BIG_MEMORY)
	constructor with filename initialization
virtual	~drwnImageCache ()
	destructor
void	initialize (const vector< string > &filenames)
	initializes the cache with a list of filenames (cache must be clear)
void	append (const string &filename)
	adds a filename to the list of filenames managed by the cache
void	clear ()
	Clear all images from the cache (cannot be called if some images are still locked). Does nothing if in big memory mode.
bool	empty () const
	returns true if the cache is empty (but may still be initialized with filenames)
size_t	size () const
	returns number of images stored in the cache
size_t	numLocked () const
	returns number of locked images in the cache
size_t	memory () const
	returns memory used by in-memory images
const string &	filename (unsigned indx) const
	return the filename for image indx
int	index (const string &filename) const
	returns the index for filename (slow)
void	lock (unsigned indx)
	lock an image for use (loads if not already in the cache)
void	lock (const string &filename)
	lock an image for use (loads if not already in the cache)
const cv::Mat &	get (unsigned indx) const
	returns an image (which must first be locked)
const cv::Mat &	get (const string &filename) const
	returns an image (which must first be locked)
void	unlock (unsigned indx)
	marks an image as free
void	unlock (const string &filename)
	marks an image as free
cv::Mat	copy (unsigned indx)
	copies an image without locking it (caller must free the image)
cv::Mat	copy (const string &filename)
	copies an image without locking it (caller must free the image)

Static Public Attributes
static size_t	MAX_IMAGES = 10000
	maximum number of images in memory at any one time
static size_t	MAX_MEMORY = 500000000
	maximum number of bytes used at any one time
static bool	GREY_IMAGES = false
	default setting for caching images in greyscale
static bool	BIG_MEMORY = false
	default setting for big memory mode

Protected Member Functions
void	enforceLimits ()
	checks memory and count limits and frees images if exceeded
virtual cv::Mat	load (const string &filename) const
	loads an image (can be overrided to perform some pre-processing)

Protected Attributes
vector< string >	_filenames
	image filenames
vector< cv::Mat >	_images
	loaded images
vector< list< unsigned >::iterator >	_free_list_map
	ref to location in _free_list
vector< unsigned >	_lock_counter
	allows for multiple locks
list< unsigned >	_free_list
	index of images that can be safely released in least-recently-used order
bool	_bGreyImages
	store images in greyscale (instead of RGB)
bool	_bBigMemoryModel
	load all images into memory (ignores MAX_IMAGES and MAX_MEMORY)
size_t	_imagesLoaded
	number of images loaded
size_t	_memoryUsed
	bytes used by loaded images
unsigned	_dbImagesLocked
unsigned	_dbImagesLoaded
size_t	_dbMaxMemUsed

Detailed Description

Caches images in memory up to a maximum number of images or memory limit.

The cache is initialized with a list of filenames. Images can then be access by index (fast) or by filename (slower). Images must be locked before being used and then unlocked so that the cache can free them if memory limits are exceeded. Images are removed under a least-recently-used (i.e., unlocked) policy. The same image can be locked multiple times. Each lock() must have a corresponding unlock(). The following code shows example usage:

vector<string> filenames = drwnDirectoryListing(directoryName, ".jpg");
drwnImageCache cache(filenames);

while (stillRunning()) {
   unsigned int indxA = getFirstImageIndex();
   unsigned int indxB = getSecondImageIndex();

   cache.lock(indxA);
   cache.lock(indxB);

   const cv::Mat imgA = cache.get(indxA);
   const cv::Mat imgB = cache.get(indxB);
   processImages(imgA, imgB);

   cache.unlock(indxB);
   cache.unlock(indxA);
}

The class can be initialized in big memory mode. In this mode all images are pre-loaded and memory/size limits are ignored, resulting in much faster calls to the lock() and unlock() functions, but may consume all available memory. Big memory mode can be enabled/disabled explicitly via the class constructor. Its default setting is controlled via the BIG_MEMORY static data member.

Note

This class is thread-safe (under Linux).

See also

drwnImagePyramidCache

---

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

• drwnImageCache.h
• drwnImageCache.cpp